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How to Use This Book 


Y The following sample pages describe the organization 
of the entries in the BASIC Compiler 2.00 Language 
Reference. 


The entries are arranged in alphabetical order. 
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Statement Name 
Statement Type 


Purpose: 


Versions: 


Format: 


Gives a brief functional description of the statement. ‘? 


Cartridge Disk Advanced Compiler 

* OK K * ok * KK * 
Indicates how each statement is supported by the 
different versions of BASIC. The symbols have the 
following meanings: 


— Three asterisks indicate that the 
statement is fully supported for the 
designated version of BASIC. 


*) Two asterisks enclosed in parentheses 
indicate that the statement is partially 
supported for the designated version. 
Any differences are explained under the 


remarks section. ‘aL 


blank No asterisks indicate that the statement is 
not supported for the designated version 
of BASIC. 


Shows the correct format for the statement. The 
syntax diagrams follow these rules: 


¢ Words in capital letters are keywords and must 
be entered as shown. They can be entered in 
any combination of uppercase and lowercase 
letters. 


Statement Name 
Statement Type 


You are to supply any items in lowercase italic 
letters. For example, you should enter the name 
of your file when filename is shown in the 
format. 


Items in square brackets are optional 


Items separated by a vertical bar (| ) mean that 
you can enter one of the separated items. For 
example: 


ON|OFF 
Means you can enter ON or OFF, but not both. 


An ellipsis (...) means that you can repeat an 
item as many times as you want. 


You must include all punctuation (except square 
brackets and vertical bars) such as commas, 
equal signs, question marks, colons, slashes, or 
backslashes where shown. 


Statement Name 
Statement Type 


Remarks: Gives detailed information about the statement. 


All unboxed information, regardless of where it 
appears, applies to all supported machines. 


Examples: These examples demonstrate how this statement can 
be used in a program. An explanation is included 
where the purpose of the example is not obvious. 


SOUND 
Statement 


YY Purpose: Generates sound through the speaker. 


Versions: Cartridge Disk Advanced Compiler 
** ok KK * 2 OK 


Format: SOUND freq, duration 


The above boxed syntax is correct for PCyr. The 
unboxed syntax is correct for all other supported 
machines. 


Remarks: 


vy freq is the desired frequency in Hertz (cycles 
per second). It must be a numeric 
expression in the range 37 to 32767. 


The above boxed information conflicts 
with the previous information given. The 
information inside the box is correct for 
PCjr. The previous information is 
correct for all other supported machines. 


The clock ticks occur 18.2 times per 


Y duration is the desired duration in clock ticks. 
second. 


This statement is only supported on PCjr. This is 
indicated by the box that encloses the statement 
heading. 


Purpose: Allows control of the hardware palette. 


Versions: Cartridge Disk Advanced Compiler 
2 K KK 


Format: PALETTE [attribute]||,color]| 
Remarks: 


attribute is an expression that evaluates to an 
integer value in the range of O to 15, 
which indicates the attribute that is to 
be changed. “ 


color is an expression that evaluates to an 
integer value that is a color in the range 
of 0 to 15 to be assigned to attribute. In 
low resolution, there are 16 attributes 
available (0 to 15). In medium 
resolution, there are 4 (0 to 3) or 16 (0 
to 15) attributes available, depending on 
the current screen mode. In high 
resolution, there are 2 (0 to 1) or 4 (O 
to 3) attributes available, depending on 
the current screen mode. The default 
attribute is always the maximum 
attribute for the current screen mode. 
For more information see ‘“‘Graphics 
Modes” in BASIC Compiler 2.00 
Fundamentals. 


Vili 


Terms and Conventions 


Throughout this book, the following terms and 
conventions apply: 


BASIC Interpreter 
is IBM Personal Computer BASIC. This is 
the interactive version of BASIC that is 
included with DOS. 

compiler is the IBM BASIC Compiler 2.00. 


disk refers to either a floppy diskette or a fixed 
disk. 


diskette refers only to a floppy diskette. 


DOS is the IBM Personal Computer Disk 
Operating System 
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BASIC Compiler 2.00 Language 
Reference 


Compiler Metacommands 


The metacommands for the BASIC Compiler 2.00 are: 


$DYNAMIC $PAGEIF 
$INCLUDE $PAGESIZE 
$LINESIZE $SKIP 
$LIST $STATIC 
$MODULE $SUBTITLE 
$OCODE $TITLE 
$PAGE 


Metacommands can be included in your source file as 
part of a remark statement; that is, metacommands 
must be inserted after the REM keyword or the single 
quote. You can have more than one metacommand in a 
remark statement. For example: 


REM $LINESIZE:120 $PAGESIZE:55 


If you use $INCLUDE, it must be the Jast 
metacommand on the line. Metacommands on one line 
can be separated by space, tab, or line feed characters; 
if the compiler sees any other character that is not part 
of a metacomman4d, it ignores the rest of the remark. 


The header for the source listing is not printed until the 
compiler scans the first line of the program for 
metacommands; this way, metacommands such as 
$TITLE can affect the first page of the source listing. 


$DYNAMIC 
Metacommand 


Purpose: Causes all subsequently dimensioned arrays to be ‘> 
dynamically allocated. : 


Versions: Cartridge Disk Advanced Compiler 
* KK 


Format: S$DYNAMIC 


Remarks:  Statically allocated arrays can only be dimensioned 
once, while dynamic arrays can be redimensioned 
using ERASE, DIM and REDIM at any point in the 
program. 


Static allocation of array space is the default. If the 
$DYNAMIC metacommand is issued, all following 
array declarations in a DIM statement are treated as 

dynamic array declarations. 2) 


SDYNAMIC 
Metacommand 


Examples: REM $DYNAMIC 


vy The following example demonstrates the use of 
static and dynamic arrays within the same program. 


120 ' $STATIC 

130 DIM C(5,5) 

149 C(5,5)=1 

145 C=5 

15@ ERASE C 

169 PRINT C,C(5,5) 

71 = 20 

180 ' $DYNAMIC 

199 DIM A(I,I,1) 

200 I = 4Q 

210 DIM B(I,1) 

220 ‘ASSIGN VALUES INTO B 
O255BR( 11) 3 4g 

227 ‘ERASE AND REDIMENSION A 
230 ERASE A 

240 REDIM A(5,5,5) 

250. ACL1.1) =a 

260 PRINT B(1,1),A(1,1,1) 
270 END 


SINCLUDE 
Metacommand 


Purpose: Tells the compiler to include source code from 
another BASIC file. 


Versions: Cartridge Disk Advanced Compiler 
* KK 


Format: $INCLUDE: ’filespec’ 
Remarks: 


filespec is a String expression for the file 
specification. It can contain a path and 
must conform to the rules outlined 
under ‘“‘Naming Files” in BASIC 
Compiler 2.00 Fundamentals, 
otherwise, a Bad file name error occurs. 


The default extension for the included 
file is .BAS. The included file must be 
in ASCII format. The file specification 
must be enclosed in single quotation 
marks. 


The compiler imbeds the specified file into the source 
file at the point where it encounters this 
metacommand. The included file may be a 
subroutine, a single line, or any type of partial 
program, but it must be written in IBM Personal 
Computer BASIC. 


You should take care that any variables in the 
included files match their counterparts in the main 
program, and that included lines do not contain 
GOTOs to nonexistent lines or similarly erroneous 
code. 


SINCLUDE 
Metacommand 


Included files can be very useful for COMMON 
declarations existing in more than one program, or 
for subroutines that you might have in an external 
library of subroutines. 


Considerations when using the BASIC program editor: 
If you create the included file using the program 
editor from within the BASIC interpreter, you must 
remember to save it using SAVE with the A option. 


Also, note that since the BASIC interpreter does not 
support the $INCLUDE metacommand, a program 
that contains a $INCLUDE metacommand may not 
run correctly if you try to run it under the 
interpreter. 


Considerations when using another editor: Use an 
editor that saves your file in ASCII format (such as 
EDLIN). 


If you use a text editor other than the BASIC 
program editor, you can create a file of lines without 
line numbers. The compiler supports sequences of 
lines without line numbers if the /N parameter is 
specified when you start the compiler. This feature 
can make it very easy to include the same file in 
many different programs. 


If line numbers are used, the following conditions 
must be met: 


1. The included lines must be in ascending order. 


2. The lowest line number of the included lines 
must be higher than the line number of the 
S$INCLUDE metacommand in the main 
program. 


SINCLUDE 
Metacommand 
3. The range of line numbers in the included file 


must numerically precede subsequent line 
numbers in the main program. 


These preceding three restrictions are removed if the 
main program is compiled with the /N parameter, 
since line numbers need not be in ascending order in 
this case. For more information, see the section 
called ‘‘Compiler Parameters” in BASIC Compiler 
2.00 Fundamentals. 


You can nest $INCLUDE up to five levels deep. If 
you are nesting them deeper than three levels, you 
must create a CONFIG.SYS file that contains the 
statement: 


FILES=xx 


Where xx is the number of nesting levels plus 5. The Aa 
maximum value of xx is 20. 


The $INCLUDE metacommand must be the last 
statement on a line. 


Examples: The first example includes the file named 
SUBR.BAS: 


90 REM $INCLUDE: ‘SUBR' 
The second example uses the $INCLUDE 


metacommand in a remark beginning with a single 
quote. The included file is named PROC.ASC: 


9999 ' $INCLUDE: 'PROC.ASC' 


SINCLUDE 
Metacommand 


The following example uses an included file that 
contains a routine for calculating the average of two 
numbers. 


10 PRINT "ENTER A NUMBER FROM 1 TO 10" 

20 INPUT A 

30 PRINT "ENTER ANOTHER NUMBER 1-10" 

40 INPUT B 

50 ' $INCLUDE: 'AVERAGE.BAS' 

6@ PRINT "THE AVERAGE OF THE TWO IS ",AVG 
70 END 


Also see the example under ''COMMON 
Statement.’ 


S$LINESIZE 
Metacommand 


Purpose: Tells the compiler to change the maximum line width “es 
in the listing file. 


Versions: Cartridge Disk Advanced Compiler 
* KK 


Format: $LINESIZE: number 

Remarks: 
number is a constant in the range 40 to 255. 
The default line size is 80 characters. 
The $LINESIZE metacommand must appear in the 
first line of your program if you want the entire 
source listing to be the same width. If $LINESIZE 


appears anywhere else in the program, it only 
changes the width of the following lines. 


Example: 1900 REM $LINESIZE: 120 


YY Purpose: 


Versions: 


Format: 


Remarks: 


Example: 


$LIST 
Metacommand 


Turns the listing of source code on and off. 


Cartridge Disk Advanced Compiler 


* 


$LIST + | - 
The default setting is $LIST+. 


$LIST+ turns the listing of source code on. $LIST- 
turns the source code listing off. 


Errors are always listed. 


$LIST is useful, for instance, if you make a change to 
a large program, and you want a listing of only the 
change. You can cause a partial listing by using 
$LIST- in the first line of the program to turn the 
source code listing off, then place $LIST + at the 
start of the new code and $LIST- at the end of the 
new code. 


190 REM $LIST- 


S$MODULE 
Metacommand 


Purpose: 


Versions: 


Format: 


Remarks: 


Example: 


10 


Allows you to change the internal module name that .) 


is passed to the Linker. 


Cartridge Disk Advanced Compiler 


* 


$MODULE : ’string’ 


string is a String expression 1 to 8 characters 
long. 


The $MODULE metacommand is useful when you 
want the module name to be different from that of 
the source file. If this metacommand is used, it must 
appear before the first executable statement. 


REM $MODULE: "TEMP" 


© Purpose: 


Versions: 


Format: 


Remarks: 


Example: 


SOCODE 
Metacommand 


Turns the listing of object code on and off. 


Cartridge Disk Advanced Compiler 


* KK 


$OCODE-+ |- 


The $O0CODE metacommand controls listing the 
generated code in the same way $LIST controls the 
source listing: $0CODE-+ turns the listing of object 
code on, $OCODE- turns the object code listing off. 


$OCODE works independently of the setting of the 
/A parameter when you compile your program. /A 
includes all the object code (unless you turn it off 
with $0CODE-); $OCODE is used to list just parts 
of the object code. 


The format of the object code listing is basically like 
an assembly listing, with code addresses and 
operation mnemonics. 


REM $0OCODE- 


11 


$PAGE 
Metacommand 


Purpose: Tells the compiler to force a new page in the ‘> 
compiler listing file. 


Versions: Cartridge Disk Advanced Compiler 
* KK 


Format: $PAGE 

Remarks: The page is forced by putting the form feed character 
(hex OC) into the listing file and writing a heading 
for the new page. 


Example: REM $PAGE 


12 


we Purpose: 


Versions: 


Format: 


Remarks: 


Example: 


S$PAGEIF 
Metacommand 


Skips to the next page if there are less than n 
printable lines left on the current page. 


Cartridge Disk Advanced Compiler 


* KK 


$PAGEIF: n 


n is a numeric constant in the range | to 25S. 


The last six lines of each page are always blank. 
These lines are not considered printable lines. 


190 REM $PAGEIF: 19 
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$PAGESIZE 
Metacommand 


Purpose: 


Versions: 


Format: 


Remarks: 


Example: 


14 


Sets the number of lines per page in the compiler Aa 
listing file. 


Cartridge Disk Advanced Compiler 


8 KK 


$PAGESIZE: n 


n is a numeric constant in the range 15 to 255. 
The default page size is 66. 


n specifies the number of lines that fit on one piece 
of paper. Pages in the listing file are separated by 
form feed characters (hex OC), and each page starts 


with a heading. - 


If n is 255, this has the effect of “‘infinite”’ page size; 
that is, no form feed characters are added to the 
listing file. 


The $PAGESIZE metacommand must appear in the 
first line of your program if you want all the pages in 
your source listing to be the same length. If 
$PAGESIZE appears anywhere else in the program, 
it only changes the length of the following pages. 


188 REM $PAGESIZE: 6@ 


wW Purpose: 


Versions: 


Format: 


Remarks: 


Example: 


S$SKIP 
Metacommand 


Skips n printable lines, or to the end of the page, 
whichever occurs first. 


Cartridge Disk Advanced Compiler 


* KK 


$SKIP: n 


n is a numeric constant in the range 1 to 255. 


The last six lines of each page are always blank. 
These lines are not considered printable lines. 


190 REM $SKIP: 19 


S$STATIC 
Metacommand 


Purpose: Causes all subsequently dimensioned arrays that use ‘- 
DIM with integer constant subscripts to be statically 
allocated. 


Versions: Cartridge Disk Advanced Compiler 
KK 


Format: $STATIC 


Remarks: Static allocation of array space is the default. 
Statically allocated arrays can only be dimensioned 
once, while dynamic arrays can be redimensioned 
using ERASE, DIM, and REDIM at any point in the 
program. 


upper bound is declared using an integer constant is 
statically allocated. If the upper bound is not an 
integer constant, the array is dynamically allocated at 
runtime; however, the array cannot be 
redimensioned or erased. 


If $STATIC is in effect, space for any array whose a“ 


SSTATIC 
Metacommand 


Examples: 100 REM $STATIC 


YY The following example demonstrates the use of 
static and dynamic arrays within the same program. 


120 * S$STATIC 

130 DIM C(5,5) 

149 C(5,5)=1 

145 C=5 

150 ERASE C 

160 PRINT C,C(5,5) 

170 I = 20 

180 ' $DYNAMIC 

190 DIM A(I,I,1) 

200 I = 40 

210 DIM B(I,1) 

220 ‘ASSIGN VALUES INTO B 
275:-Bt1.1) = 17 

227 ‘ERASE AND REDIMENSION A 
230 ERASE A 

240 REDIM A(5,5,5) 

250 A(1,1,1) = 3 

260 PRINT B(1,1),A(1,1,1) 
270 END 
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SSUBTITLE 
Metacommand 


Purpose: 


Versions: 


Format: 


Remarks: 


Example: 
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Sets compiler listing page subtitle. 


Cartridge Disk Advanced Compiler 


* 


$SUBTITLE: ’string’ 


‘string’ is a character string constant, enclosed 
in single quotation marks. The 
maximum length of the string is 60 
characters. If a program does not 
contain a $SUBTITLE command, the 
null string is used as a subtitle. 


The specified string is printed on each page of the 
listing. A long title string may be truncated if 
$LINESIZE is set to a value less than 80. 


The $SUBTITLE metacommand must appear in the 
first line of your program if you want the title to 
appear on the first page of the source listing. If 
S$SUBTITLE appears anywhere else in the program, 
it only affects the following pages. 


100 ' $SUBTITLE: ‘Entry Routine’ 


wv Purpose: 


Versions: 


Format: 


Remarks: 


Example: 


$ TITLE 
Metacommand 


Provides a title for the compiler listing. 


Cartridge Disk Advanced Compiler 


KK 


$TITLE: ’string’ 


‘string’ is a character string constant, enclosed 
in single quotation marks. The 
maximum length of the string is 60 
characters. 


The specified string is printed on each page of the 
listing. A long title string may be truncated if 
$LINESIZE is set to a value less than 80. 


The $TITLE metacommand must appear in the first 
line of your program if you want the title to appear 
on the first page of the source listing. If $TITLE 
appears anywhere else in the program, it only affects 
the title on the following pages. 


100 ' $TITLE: ‘Update Program' 
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ABS 


Function 
Purpose: Returns the absolute value of the expression x. 
Versions: Cartridge Disk Advanced Compiler 
kK #9 ek ee 
Format: v = ABS(x) 
Remarks: x can be any numeric expression. 
The absolute value of a number is always positive or 
Zero. 
Example: This example shows that the absolute value of -35 is 
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positive 35. 
PRINT ABS(7*(-5)) 
Results: 


$9 


YY Purpose: 


Versions: 


Format: 


Remarks: 


Example: 


ASC 
Function 


Returns the ASCII code for the first character of a 
string (x$). 


Cartridge Disk Advanced Compiler 


* kk * * 2K * KK 


v = ASC(x$) 
x$ can be any string expression. 


The result of the ASC function is a numeric value 
that is the ASCII code of the first character of the 
string x$. See Appendix B, ‘“‘ASCII Character 
Codes’’, for a list of ASCII codes. If x is null, an 
Illegal function call error is returned. 


The CHR$ function is the inverse of the ASC 
function, and it converts the ASCII code to a 
character. 


This example shows that the ASCII code for a capital 
T is 84. PRINT ASC(“TEST’’) would work just as 
well. 


100 X$ = "TEST" 
200 PRINT ASC(X$) 


Results: 


84 
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ATN 
Function 


Purpose: Returns the arctangent of x. fy 


Versions: Cartridge Disk Advanced Compiler 
kK KK 2k * Kk 


Format: v= ATN(x) 

Remarks: x can be a numeric expression of any type. 
The ATN function returns the angle whose tangent is 
x. The result is a value in radians in the range -PI/2 


to PI/2, where PI=3.141593. 


If you want to convert radians to degrees, multiply 
by 180/PI. 


Examples: The first example shows the use of the ATN function ‘> 
to calculate the arctangent of 3. 


100 PRINT ATN(3) 


Results: 


1.249046 
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ATN 
Function 


The second example finds the angle whose tangent 
is 1. It is .7853983 radians, or 45 degrees. 


199 PI=3.141593 

200 RADIANS=ATN(1) 

300 DEGREES=RADIANS*18@/PI 
400 PRINT RADIANS ,DEGREES 


Results: 


~fO0S903 45 


BEEP 
Statement 


Purpose: Causes the speaker to sound. 


Versions: Cartridge Disk Advanced Compiler 


Format: BEEP 


Remarks: The BEEP statement causes the speaker to sound at 
800 Hz for 1/4 second. BEEP has the same effect 


as: 


PRINT CHR$(7); 
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Example: 


BEEP 
Statement 


In this example, the program checks to see if X is out 
of range. If it is, the computer warns you by 
beeping. 


199 IF X < 2@ THEN BEEP 
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BLOAD 


Command 
Purpose: Loads a memory image file into memory. (> 
Versions: Cartridge Disk Advanced Compiler 


Format: 


Remarks: 
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2 2 3k re 2 ok 2 2 ok 2k 2k 


BLOAD filespec |,offset| 


filespec is a String expression for the file 
specification. It can contain a path and 
must conform to the rules outlined 
under ‘“‘Naming Files” in BASIC 
Compiler 2.00 Fundamentals, 
otherwise, a Bad file name error occurs. 


offset is a Single-precision value in the range 0 ‘> 
to 1048575. This is an offset at which 
the file is loaded into the current 
segment specified by the latest DEF 
SEG statement. 


If offset is omitted, the offset specified at BSAVE is 
assumed. That is, the file is loaded into the same 
location from which it was saved using BSAVE. 


When a BLOAD command is executed, the named 
file is loaded into memory starting at the specified 
location. 


If the device name is omitted, the DOS default drive 


is used. a“ 


BLOAD 
Command 


BLOAD is intended for use with a file that has 
previously been saved with BSAVE. BLOAD and 
BSAVE are useful for loading and saving machine 
language programs, but they are not restricted to 
machine language programs. Any segment can be 
specified as the target or source for these statements 
through the DEF SEG statement. You have a useful 
way of saving and displaying screen images: save 
from or load to the screen buffer. See also “‘Calling 
Assembly Language Subprograms ” in BASIC 
Compiler 2.00 Fundamentals for more information. 


Warning: BASIC does not check the offset of the 
current segment where you are loading with BLOAD. 
You can use BLOAD anywhere in memory, but it is 
your responsibility to assure that a file loaded with 
BLOAD does not conflict with the current contents of 
memory. 


See the ‘‘Memory Information” section in BASIC 
Compiler 2.00 Fundamentals for more information. 


z/ 


BLOAD 
Command 


Example: 


This example loads the screen buffer for the 
Color/Graphics Monitor Adapter, which is at 
segment address HB8000. If you were loading the 
screen buffer for the IBM Monochrome and Printer 
Adapter, you would have to change line 300 to read 
&HBOOO. Line 500 loads PICTURE at offset 0, 
segment &HB800. 


190 ‘load the screen buffer 

200 ‘point SEG at screen buffer 

300 DEF SEG= &HB8@a 

490 ‘load PICTURE into screen buffer 
500 BLOAD "PICTURE" ,@ 


The example for the BSAVE command (see the 
next entry) illustrates how PICTURE was saved. 


YY Purpose: 


Versions: 


Format: 


Remarks: 


BSAVE 
Command 


Saves portions of the computer’s memory on the 
specified device. 


Cartridge Disk Advanced Compiler 


OK 7 OK * KK * OK 


BSAVE /filespec, offset, length 


filespec is a String expression for the file 
specification. It can contain a path and 
must conform to the rules outlined 
under “‘Naming Files” in BASIC 
Compiler 2.00 Fundamentals, 
otherwise, a Bad file name error occurs. 


of fset is a Single-precision value in the range O 
to 1,048,575. This is the offset into the 
segment declared by the last DEF SEG. 
Saving starts from this location. See 
‘““‘DEF SEG Statement.”’ 


length is an integer expression in the range 1 to 
65535. This is the length of the 


memory image to be saved. 


If offset or length is omitted, a Syntax error occurs 
and the save is canceled. 


If the device name is omitted from filespec, the DOS 
default disk drive is used. 
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BSAVE 
Command 


When you use the DEF SEG statement, you can 
specify any segment as the source segment for the 
BSAVE data. For example, you can save an image “a 
of the screen by doing a BSAVE of the screen 
buffer. 


Examples: As explained under ““BLOAD Command’”’, the 
segment address of the 16K-byte screen buffer for 
the Color/Graphic Monitor Adapter is HB8000. 
The segment address of the 4K-byte screen buffer 
for the IBM Monochrome Display and Printer 
Adapter is HBOOOO. 


The DEF SEG statement must be used to set up the 
segment address to the start of the screen buffer. 
The offset of 0 and length &H4000 specify that the 
entire 16K-byte screen buffer is to be saved. 


100 ‘Save the color screen buffer “a 
200 ‘point segment at screen buffer 

300 DEF SEG= &HB&8dd 

490 ‘save buffer in file PICTURE 

500 BSAVE "PICTURE" ,@,&H4000 
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YY Purpose: 


Versions: 


Format: 


Remarks: 


CALL 
Statement 


Calls and transfers control to a subprogram. 


Cartridge 
ae, 


Disk Advanced Compiler 


CALL subname |(parameter |,parameter]....)| 


subname 


parameter 


is the name of the subprogram that you 
wish to call. For external subprograms, 
subname must be recognized by LINK 
as a PUBLIC symbol. The procedure 
for declaring subname depends on the 
language in which the subprogram is 
written: 


For BASIC Subprograms: 

subname is the name declared in the 
SUB statement. 

For Macro Assembler Subprograms: 


subname must be a name declared ina 
PUBLIC statement. 


is the name of a parameter to be passed 
to the subprogram. 


The CALL statement can be used to invoke BASIC 
compiled subprograms and Macro Assembler 


subprograms. 


CALL 
Statement 


The parameter(s) is part of the formal parameter list. 
Parameters are optional and limited in number to 60. 
They enable communication of values to and from 
the subprogram. 


When a simple variable or array element is passed to 
a subprogram, it is passed by reference. This means 
that the subprogram can change the value of the 
variable in the calling routine by assigning a new 
value to its corresponding formal parameter in the 
formal parameter list through an assignment 
statement or any other statement that assigns values 
to a memory location. 


In Macro Assembler subprograms, to change the 

value assigned to a formal parameter the assembly 

language subprogram must store the value in the 

memory location pointed to by the two byte offset 

passed to the subprogram by the CALL statement. “& 


Expressions can also be passed as arguments to 
subprograms. When the expression is encountered in 
the formal parameter list, it is assigned to a 
temporary variable. This variable is then passed by 
reference to the subprogram. This is functionally 
equivalent to call by value, where the value itself is 
passed rather than that value’s position in the 
parameter list. 


Array arguments can be passed to BASIC 
subprograms using the CALL statement. An array 
argument is specified by following the array name 
with parentheses. For example: 


CALL MATADD2(5,10,ARRAY1() ,ARRAY2() , TOTAL() ) 
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CALL 
Statement 


Arrays should not be passed as formal parameters to 
assembly language subprograms; instead, the base 
element of the array should be passed by reference if 
the entire array needs to be accessed by the assembly 
language subprogram. 


Two types of programming errors are commonly 
made in calling BASIC subprograms: 


¢ Formal parameter lists in which the order, type, 
or number of arguments passed to the 
subprogram do not exactly match the 
corresponding formal parameters in the 
subprogram. 


The compiler does not check for this 
discrepancy. An error message is not generated, 
but subtle errors may occur. For example, type 
mismatching can occur when an integer 
argument is mistakenly matched with a 
parameter that expects to receive a 
single-precision argument. 


e  Aliasing of variables. 


Aliasing occurs whenever an argument passed to 
a subprogram can be referenced in the 
subprogram more than one way. This 
commonly occurs when the same nonexpression 
argument is passed more than once to a 
subprogram. Passing variables both in 
COMMON and as an argument, or passing both 
an array element and the array itself, also cause 
aliasing. The BASIC Compiler 2.00 does not 
support or check for aliasing. If aliasing of 
variables occurs, the results are unpredictable. 
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CALL 
Statement 


When transporting BASIC Interpreter assembly 
language subprograms to the compiler, note that 
since the BASIC Compiler 2.00 allows strings up to 
32767 bytes in length, the string descriptor requires 
4 bytes rather than 3 (low byte, high byte of the 
length, followed by low byte, high byte of the 
address). If your assembly language subprogram 
uses String arguments, you may need to recode it to 
take this difference into account. 


The starting address of the subprogram is determined 
by the Linker; DEF SEG is unimportant when 
calling a Macro Assembler subprogram from a 
compiled program. 


Example: The following program calls a subprogram that 
converts decimal notation into binary notation. 


19@ REM BINARY CONVERSION 
LLOSUEr INE A686. C1 
120 PRINT "DECIMAL TO BINARY CONVERSION" 
13@ PRINT 
149 INPUT "ENTER NUMBER FROM @ TO 32767: "3; B 
15@ CALL BINARY(B,BINSTR$) 
160 PRINT "THE BINARY VALUE IS " + BINSTR$ 
17@ END 
18@ REM CONVERT TO BINARY REPRESENTATION 
199 SUB BINARY(C,D$) STATIC 
200 DIM A(15) 
e1Gceon ft ss-'s10 YU STEPS 
220 eG. <. 27.1 THEN ALI = 0s GOrG 259 
230 ACI) = 1 

fee Ge 2) 


250 NEXT I 

260 REM CONVERT TO STRING FOR VIEWING PURPOSES 

270 D¢ = Weel 

LOU FOR. =. bo 1 O-PS TER =2 

290 D$ = D$ + RIGHT$(STRS$(A(T)),1) A 
300 NEXT I — 
31@ END SUB 
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CALL 
Statement 


The following program, REC.BAS, calls an 
assembly language subprogram called SORT that 
sorts 50 integers stored in an array. 


100 REM program REC 

110 DEFINT A-Z 

120 DIM A(5@) 

130 OPEN "RECEIPTS" FOR INPUT AS #1 
140 FOR I=1 TO 5@: INPUT #1,A(I): NEXT 
150 CALL SORT(A(@), A(5@)) 


In line 150, the addresses of the first and last integer 
to be sorted are passed as arguments to SORT. 
SORT was declared PUBLIC in the Macro 
Assembler, and was linked to REC.BAS by 
responding to the Object Modules prompt from the 
Linker as follows: 


Object Modules [OBJ]: REC+SORT 


For more information, see the ‘‘SUB and END SUB 
and EXIT SUB Statement”’ and the ‘““CALLS 
Statement,” in this book and the ‘‘Modular 
Programming” section in BASIC Compiler 2.00 
Fundamentals. 
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CALLS 
Statement 


Purpose: 


Versions: 


Format: 


Remarks: 
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Calls and transfers program control to subprograms 
written in another language, or assembly language 
subprograms created with the IBM Personal 
Computer Macro Assembler. 


Cartridge Disk Advanced Compiler 


6 KK 


CALLS subname|(parameter|,parameter|...) | 


subname is the name of the subprogram you 
are calling. 


parameter is the name of any parameter you 
want passed to the subprogram. 


The CALLS statement works like the CALL 
statement with a few differences. 


The CALLS statement handles communication of 
parameters to the subprogram differently from the 
CALL statement. For each parameter in the formal 
parameter list, a segment and an offset for that 
argument is pushed onto the stack; the segment 
location of the compiler’s DATA segment and the 
offset of the argument into the DATA segment. 


Note: Array base arguments cannot be passed 
as parameters in a CALLS statement. 


CALLS 
Statement 


CALLS is meant to be used for existing subprograms 
that expect both the segment and offset of each 
argument to be on the stack upon routine entry. 


For related information, see the ““CALL Statement.”’ 


See also ''Modular Programming" in BASIC 
Compiler 2.00 Fundamentals. 
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CALL ABSOLUTE 
Statement 


Purpose: Transfers control to a machine language subroutine. 


Versions: Cartridge Disk Advanced Compiler 
* KK 


Format: CALL ABSOLUTE ([parameter|,parameter]...| 
intvar) 


Remarks: 


parameter is the name of any argument that is to 
be passed to the machine language 
subroutine. 


intvar is the name of an integer variable 


The word ABSOLUTE must be used. It is a global & 
symbol that is the name of a library routine that 
transfers control to your subroutine. 


The parameters are optional. They are the arguments 
that are passed to the machine language subroutine. 


intvar must be included in the parameter list. The 
value of intvar is the starting memory location of the 
subroutine as an offset into the current segment of 
memory as defined by the last DEF SEG statement. 
intvar iS an argument to the ABSOLUTE routine, but 
is not passed as an argument to your machine 
language subroutine. If other parameters are 
included in the list, intvar must appear last. The 
value of intvar must be set to the offset value before 
the CALL ABSOLUTE statement is executed. A ae 
DEF SEG statement must be executed before the 
CALL ABSOLUTE statement is performed to 
ensure that the code segment is correct. 
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Example: 


CALL ABSOLUTE 
Statement 


Because the subroutine is not linked to the BASIC 
Compiler calling module, the machine language 
subroutine does not have segment naming 
requirements as defined by CALL and CALLS. 


In a compiled program, you can put the routine into 
an integer variable array by following these steps: 


1. Dimension an integer array so the number of 
elements in the array is the number of words, not 
bytes, in the subroutine. 


2. Use a FOR...NEXT loop to read the hex values 
for the machine language code from DATA 
statements into the array. 


3. Remember to call VARPTR(array name) to 
define the offset before you perform the CALL 
ABSOLUTE. 


See ‘“‘Calling Assembly Language Subprograms”’ in 
BASIC Compiler 2.00 Fundamentals for more 
information. 


This example calls a subroutine located at 
OFFSET=0 of the segment returned by VARPTR. 
Parameters A, B, and C are passed to the subroutine. 


1000 DEF SEG = VARPTR(ARRAY(1)) ‘set segment 


1010 OFFSET% 0 ‘set offset 
1020 CALL ABSOLUTE {(A,B,C,OFFSET?) 
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CDBL 


Function 
Purpose: Converts x to a double-precision number. (‘> 
Versions: Cartridge Disk Advanced Compiler 


Format: 


Remarks: 


Example: 
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* KK * KOK * K OK 


v = CDBL(x) 
x can be any numeric expression. 


Rules for converting from one numeric precision to 
another are followed as explained in BASIC 
Compiler 2.00 Fundamentals. See also ““CINT”’ and 
““CSNG” functions for converting numbers to 
integer and single-precision. 


The value of CDBL(A) is accurate only to the 

second decimal place after rounding. This is so = 
because only two decimal places of accuracy are ; 
supplied with A. 


110 A = 454.67 
12@ PRINT A;CDBL(A) 


Results: 


454.67 454.6699829191563 


wy) Purpose: 


Versions: 


Format: 


Remarks: 


CHAIN 
Statement 


Transfers control to another program. 


Cartridge Disk Advanced Compiler 


CHAIN filespec 
filespec is a string expression for the file 


specification. It can contain a path and 
must conform to the rules outlined 
under ‘“‘Naming Files” in BASIC 
Compiler 2.00 Fundamentals, 
otherwise, a Bad file name error occurs. 


The CHAIN statement performs two different ways 
depending on whether you are using the 
BASRUN20.EXE runtime module or not (whether 
you omitted or used the/O parameter). 


When you use BASRUN20.EXE, chaining works as 
in the interpreter. Files are left open, device status is 
preserved, and you can use COMMON to pass 
parameters to the chained-to program. Both the 
chaining program and the chained-to program must 
have been compiled without the /O parameter. 
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CHAIN 
Statement 


Example: 
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In a program that does not use BASRUN20.EXE, 
CHAIN works just like RUN filespec, with the 
exception that both the chaining program and the 
chained-to program must have been compiled with 
/O. 


Note: If you wish to share variables between 
programs, you should use the COMMON 
statement. See “COMMON Statement” for 
more information. 


This example shows how to execute a second 
program from within your application. 


CHAIN "A: OVERLAY2.EXE" 


CHDIR 
Command 


© Purpose: Changes the current directory. 


Versions: Cartridge Disk Advanced Compiler 
2k OK * KK * * K 


Format: CHDIR path 
Remarks: 


path is a String expression, not exceeding 63 
characters, identifying the new directory 
that becomes the current directory. For 
more information on paths refer to 
‘“‘Naming Files’’ and ‘“Tree-Structured 
Directories” in BASIC Compiler 2.00 


Fundamentals. 
wy Examples: 
ROOT 
DOS LANG 
pe ae 
DOS21 DOS30 BASIC FORTRAN PASCAL 
INT COMPILER 
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CHDIR 
Command 


(The examples that follow refer to the tree structure 
shown on the previous page.) 


To change to the root directory from any ‘> 
subdirectory, use: 


Ghote \ 


To change to the directory DOS30 from the root 
directory, use: 


CHDIR "DOS \DOS30" 


To change to the directory FORTRAN from the 
directory LANG, use: 


CHDIR "FORTRAN" 


To change from the directory DOS21 to the 
directory DOS, use: “a 


ooo ees 


a4 


© Purpose: 


Versions: 


Format: 


Remarks: 


Examples: 


CHRS$ 
Function 


Converts an ASCII code to its character equivalent. 


Cartridge Disk Advanced Compiler 


* OK * KO KK KK 


v§ = CHRS(n) 
n must be in the range O to 255. 


The CHRS$ function returns the one-character string 
with ASCII code n. CHR$ is commonly used to send 
a special character to the screen or printer. For 
instance, the BEL character, which beeps the 
speaker, might be included as CHR$(7) as a preface 
to an error message (instead of using BEEP). 


See Appendix A, ‘“‘ASCII Character Codes’’, for 
more information. See also ‘‘ASC Function,”’ for 
information on how to convert a character back to its 
ASCII code. 


This example prints the character equivalent of 
ASCII code 66. 


PRINT CHR$(66) 


Results: 


B 
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CHR$ 


Function 


46 


The next example sets function key F1 to the string 


‘““FILES” plus Enter. This is a good way to set the 


function keys so Enter is automatic when you press Aa 


the function key. 


KEY 


Ly FILES- *CHR$(13) 


The following example is a program that shows all 
the displayable characters, along with their ASCII 
codes, on the screen in 80-column width. 


£19 C3 

L2@ FOR 141° TO 255 

130 ‘ ignore nondisplayable characters 

149 IF (I>6 AND I<14) OR (I>27 AND I<32) THEN 19000 
15@ COLOR @,7 ‘ black on white 

160 PRINT USING "###"; I ; ' 3-digit ASCII code 

170 COLOR 7,@ ' white on black 

fae Vein: - + CHRS(T) 300 4 

190 IF POS(@)>75 THEN PRINT ' go to next line “> 
1900 NEXT I 


YU Purpose: 


Versions: 


Format: 


Remarks: 


Examples: 


CINT 
Function 


Converts x to an integer. 


Cartridge Disk Advanced Compiler 


* OK * K * KO * KOK 


vse CIN T(x) 


x can be any numeric expression. If x is not in 
the range -32768 to 32767, an Overflow error 
occurs. 


x is converted to an integer by rounding the 
fractional portion. 


See “FIX” and “INT” functions, both of which also 
return integers. See the ““CSNG” and ““CDBL”’ 


functions for converting numbers to single-precision 
or double-precision. 


Observe in both examples how rounding occurs. 
PRINT CINT(45.499) 


Results: 


45 


PRINT CINT(-2.89) 
Results: 


=3 


47 


CIRCLE 
Statement 


Purpose: Draws an ellipse on the screen with center (x,y) and 
radius r. 


Versions: Cartridge Disk Advanced Compiler 
* KK * KK * 


Graphics mode only. 
Format: CIRCLE (x,y),r |, attribute |,start,end |,aspect]]] 
Remarks: 


(x,y) are the coordinates of the center of the 
ellipse. The coordinates can be given in 
either absolute or relative form. See 
‘Specifying Coordinates” under 
‘““Graphics Modes” in BASIC Compiler “a 
2.00 Fundamentals. 


yr is the radius (major axis) of the ellipse 
in points. 
attribute is an integer expression that specifies a 


color attribute. In SCREEN 1, 
(medium resolution), attribute can range 
from 0 to 3. In SCREEN 2, (high 
resolution), attribute can be O or 1. 


The default color attribute for the 
foreground is the maximum color 
attribute for that screen mode. 


The default color attribute for the 
background is always zero. 
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CIRCLE 
Statement 


CIRCLE 
Statement 


start, end are angles in radians and can range from 
-2*PI to 2*PI, where PI=3.141593. 


start and end specify where the drawing ‘> 
of the ellipse begins and ends. The 

angles are positioned in the standard 
mathematical way, with 0 to the right 

and going counterclockwise: 


Pl/2 
P| O25 


arrive 


is not allowed), the ellipse is connected 
to the center point with a line, and the 
angles are treated as if they were 
positive (note that this is not the same 
as adding 2*PI). 


If the start or end angle is negative (-0 “ 
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CIRCLE 
Statement 


The start angle can be greater or less 
than the end angle. For example, 


110 PI=3.141593 


12Q SCREEN 1 
13@ CIRCLE (160,100) ,60,,-PI,-PI/2 


draws a part of a circle similar to the 
following: 


aspect is a numeric expression. 


aspect affects the ratio of the x-radius to the y-radius. 
The default for aspect is 5/6 in medium resolution 
and 5/12 in high resolution. These values give a 
visual circle assuming the standard screen aspect 
ratio of 4/3. 


If aspect is less than 1, then ris the x-radius. That is, 
the radius is measured in points in the horizontal 
direction. If aspect is greater than 1, then r is the 
y-radius. For example, 


110 SCREEN 1 
120 CIRCLE (160,100) ,60,,,,5/18 


draws an ellipse like this: 


ro | 


CIRCLE 
Statement 
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In many cases, an aspect of 1 results in nicer-looking 
circles in medium resolution. It also causes the circle 
to be drawn somewhat faster. 


The last point referenced after a circle is drawn is the 
center of the circle. 


Points that are off the screen are clipped, and no 
error occurs. 


Example: 


CIRCLE 
Statement 


The following example draws a face. 


119 
129 
139 
149 
159 
160 
179 
189 
199 
200 
210 
220 
230 


PI=3.141593 

SCREEN 1 ' medium res. graphics 
COLOR @,1 ' black background, palette 1 
‘two circles in color 1 (cyan) 
CIRCLE (120,50) ,10,1 

CIRCLE (200,50) ,10,1 

‘two horizontal ellipses 

CIRCLE (1205587530. 5;.5/18 

CIRCLE (200,50) .30,.,,.5/18 

‘arc in color 2 (magenta) 

CIRCLE (160.@33 4502 --1:3*PI,. 1.7*P!I 
‘arc, one side connected to center 
CIRCLE (3GGgee eet 4" P 1 =1.6"P1 
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CLEAR 
Command 


Purpose: _ Sets all numeric variables to zero and all string 
variables to null. The options set the amount of 
stack space. 


CLEAR is supported for the runtime module only. 


Versions: Cartridge Disk Advanced Compiler 


Format: CLEAR [,[7] [,s]] 


Remarks: 


n is an integer expression. This parameter is 
ignored by the compiler. If you are compiling 
a program that was originally written for the 
interpreter, the value for n can be included 
without causing an error. 


s is an integer expression that sets aside stack 
space for the BASIC compiler. The default is 
768 bytes. Include s if you use many nested 
GOSUB statements or FOR...NEXT loops in 
your program, or if you use PAINT to do 
complex scenes. 
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CLEAR 
Command 


CLEAR performs the following actions: 

e Closes all files. 

e Clears all COMMON variables. 

e Resets the stack and string space. 

« Releases all diskette buffers (that is, space 


allocated for file buffers is returned to string 
space). 


e Resets all variables and arrays to zero or null. 


e Resets DEF SEG to the default and clears the 
definitions of any USR functions. 


e Turns off any sound that is running and resets to 
Music Foreground. 


e Resets PEN and STRIG to OFF. 


Because type definitions are determined when the 
program is compiled, any definitions set by DEFtype 
are not cleared. 


rs) 


CLEAR 
ommand 


If you use CLEAR, it should be the first statement in 
your program because it erases all variables. For 
more information on paging, see the “SCREEN 
Statement” and the “PCOPY Statement.” 


The ERASE statement is useful to free some 
memory without erasing all the data in the program. 


It erases only specified arrays from the work area. 
See the ““ERASE Statement.”’ 


Example: 


CLEAR 
Command 


This example clears all data from memory (without 
erasing the program): 


CLEAR 


The next example clears the data and sets the size of 
the stack to 2000 bytes: 


CLEAR ,,2000 


CLOSE 
Statement 


Purpose: Terminates I/O to a device or file. 


Versions: Cartridge Disk Advanced Compiler 
2K OK ** OK * OK ok ** kK 


Format: CLOSE |[[#] filenum [,[#] filenum|....] 
Remarks: 


filenum — is the number used on the OPEN 
statement. 


The association between a particular file or device 
and its file number stops when CLOSE is executed. 
Subsequent I/O operations specifying that file 
number are invalid. The file or device can be opened 
again using the same or a different file number, or 
the file number can be reused to open any device or 
file. 


A CLOSE to a file or device opened for output 
causes the final buffer to be written to the file or 
device. 


A CLOSE with no file numbers specified causes all 
open devices and files to be closed. 


Executing a RESET, RUN, STOP, SYSTEM, or 


Ctrl-Break causes all open files and devices to be 
automatically closed. 


opening files. 


See also ‘“‘SOPEN Statement”’ for information about 2 


Examples: 


CLOSE 
Statement 


This example causes the files and devices associated 
with file numbers 1, 2, and 3 to be closed. 


19@ CLOSE #1,#2,#3 


This example causes all open devices and files to be 
closed. 


10Q CLOSE 
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CLS 
Statement 


Purpose: Clears the screen. (‘> 


Versions: Cartridge Disk Advanced Compiler 
7 OK 2 ok 2 6 2 ok 


Format: CLS 


Remarks: When the screen is in text mode, the active page is 
cleared to the background color. See also “COLOR” 
and ‘“‘“SCREEN” statements. 


When the screen is in graphics mode the entire 
screen buffer is cleared to the background color. 


The CLS statement also returns the cursor to the 
home position. In text mode, this means the cursor is 
located in the upper left corner of the screen. In 
graphics mode, the home position is the center of the 
screen. This becomes the "last point referenced" for 
future graphics statements. In medium resolution the 
center of the screen is (160,100). In high resolution 
the center of the screen is (320,100). 


Changing the screen mode or width by using the 
SCREEN or WIDTH statements also clears the 
screen. “> 
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Example: 


CLS 
Statement 


When you are using the VIEW statement, CLS clears 
only the current viewport. To clear the entire screen 
you must use VIEW to disable the active viewport, 
and then use CLS to clear the screen. 


In color graphics mode, this example clears the 
screen to blue. 


11@ SCREEN 0,0,@ 


128 COLOR 19,1 
Pay GL} 
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COLOR 
Statement 


Purpose: Sets the colors for the foreground, background, and 
border screen. See ‘‘Text Mode” in BASIC 
Compiler 2.00 Fundamentals for an explanation of 
these terms. 


Format: The syntax of the COLOR statement depends on 
whether you are in text mode or graphics mode, as 


set by the SCREEN statement. 
In text mode, you can set the following: 


Screen 0 Foreground, maximum color attribute 
of 15 
Character blink, if desired 
Background, maximum color attribute 
of 7 
Border, maximum color attribute of 
ES 


In graphics mode, the border is the same as the 
background color. You can set the following: 


Screen 1 Background, maximum color attribute 
of 15 (0-15) 
Palette, 1 of 2 palettes (O or 1), 
maximum color attribute of 3 in each 
palette (0-3) 
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COLOR 
Statement 


COLOR 


Statement 
The COLOR Statement in Text Mode 
Versions: Cartridge Disk Advanced Compiler ‘> 


Format: COLOR [foreground] |,[ background |,border}|| 
Remarks: 


foreground is a numeric expression in the range 0 
to 31, representing the character 
color. 


background is anumeric expression in the 
range O to 7 for the background color. 


border is a numeric expression in the range O 
to 15. It is the color for the border 
screen. ‘> 


If you have the Color/Graphics Monitor Adapter, the 
following colors are allowed as values for foreground: 


QO Black 8 Gray 

1 Blue 9 Light Blue 

2 Green 10 Light Green 

3 Cyan 11 Light Cyan 

4 Red 12 Light Red 

5 Magenta 13 Light Magenta 

6 Brown 14 Yellow 

7 White 15 High-intensity White 


Colors and intensity can vary depending on your 
display device. 
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COLOR 
Statement 


You might like to think of colors 8 to 15 as “‘light”’ or 
‘“‘high-intensity”’ values of colors 0 to 7. To obtain 
the “‘light’”’ shade for any of the colors 0 to 7, add 8 
to that color value. 


You can make the characters blink by setting 
foreground equal to 16 plus the number of the desired 
color. That is, values from 16 to 31 cause blinking 
characters. 


You can select only color attributes O through 7 for 
background in text mode. The foreground color 
attribute can equal the background color attribute. 
This makes any character displayed invisible. 
Changing the foreground or background color 
attribute makes subsequent characters visible again. 


If you have the IBM Monochrome Display and 
Printer Adapter, the following values can be used 
for foreground: 


0 Black when background is O or 7, green 
otherwise. 

1 Underlined green. 

2-7 Green. 

8 Black when background is O or 7, intense 


green otherwise. 


9 Intense underlined green. 
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COLOR 


Statement 
10-15 Intense green. 
16 Blinking black when background is 0 or 7, 
blinking green otherwise. 


17 Underlined blinking green. 
18-23 Blinking green. | 


24 Blinking black when background is O or 7, 
blinking green otherwise. 


25 Intense blinking underlined green 
26-31 Intense blinking green. 
For background, you can select the following values: 


0-6 Black “a 


7 Green, if foreground is O, 8, 16, or 24. 
Black otherwise. 


Note: The color attributes: 


all produce reverse video (black on green). 


All other color combinations produce some form 
of standard video (green on black) on the IBM 


Monochrome Display. >) 
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COLOR 
Statement 


Any parameter can be omitted. Omitted 
parameters assume the old value. 


If the COLOR statement ends in a comma (,), 
you get a Syntax Error error. For example, 


CUR Lets 
is invalid. 


Any values entered outside the range O to 255 
result in an Illegal function call error. 


Examples: This statement sets a yellow foreground, a blue 
background, and a black border screen. 


COLOR 14,1,@ 


The following example can be used with either the 
Color/Graphics Monitor Adapter or the IBM 
Monochrome Display and Printer Adapter: 


119 
120 
139 
149 
159 
16Q 
17 
180 
199 
200 
210 
220 
230 
240 


PRINT "Enter your "; 

COLOR 15,@ ‘highlight next word 

PRINT "password"; 

COLOR 7 ‘return to default (white on black) 
PRINT " here: "; 

COLOR @ ‘invisible (black on black) 

INPUT PASSWORD$ 

IF PASSWORD$="Secret" THEN 220 

' blink and highlight error message 

COLOR 31: PRINT "Wrong Password": COLOR 7 
GOTO 110 

COLOR @,7 ‘reverse image (black on white) 
PRINT "Program continues..."; 

COLOR 7,@ ‘return to default (white on black) 
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COLOR 
Statement 


The COLOR Statement in Graphics Mode 


Versions: Cartridge Disk Advanced Compiler 


Graphics mode only. 


Format: 


For Screens 1| and 2: 
COLOR [background] |, palette] 


Remarks: Screen tl: 


background _ is an integer expression in the range 0 
through 15. It specifies the 
background color attribute. 


palette is an integer expression. It selects 
one of two palettes of color. The 
maximum color attribute in each 
palette is 3. 
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COLOR 
Statement 


In SCREEN 1, the COLOR statement sets a 
background color and chooses one of two palettes 
with four color attributes each (0-3). Color 
attribute 0 is always the current background. You 
can select one of three color attributes for the 
foreground color to be used with PSET, PRESET, 
LINE, CIRCLE, PAINT, VIEW, and DRAW. 


Note: Only PCjr supports color in high 
resolution. Using COLOR in high resolution on 
any other machine results in in an Illegal 
function call error. 


The colors selected when you choose each palette are 
as follows: 


Attribute Palette 0 Palette 1 


1 Green Cyan 
Zz Red Magenta 
3 Brown White 


If palette is an even number, palette O is selected. 
This associates green, red, and brown to the color 
attributes 1, 2, and 3. 
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COLOR 
Statement 


72 


If palette is an odd number, palette 1 is selected. 
This associates cyan, magenta, and white to the color 
attributes 1,2, and 3. 


Graphics mode can display text in any of the three 
colors available in the current palette. However, if 
you are not using a U.S. keyboard, refer to the 
““GRAFTABL Command” in Disk Operating System 
reference for information regarding additional 
character support for the Color/Graphics Monitor 
Adapter and other keyboards. 


The color selected for background can be the same 
as any of the palette colors. 


Examples: 


COLOR 
Statement 


Any parameter can be omitted from the COLOR 
statement. Omitting parameters does not cause the 
current background or palette to change. 


Any values entered outside the range 0 to 255 cause 
an Illegal function call error. Previous values are 
retained. 


This statement sets the background to light blue and 
selects palette O. 


11@ SCREEN 1 
120 COLOR 9,@ 


In the next example, the background stays light 
blue, and palette 1 is selected. 


COEOR- 44 
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COM(n) 
Statement 


Purpose: Enables or disables trapping of communications 
activity to the specified communications adapter. 


Versions: Cartridge Disk Advanced Compiler 
** OK ** K * OK 


Format: COM(n) ON 
COM(n) OFF 
COM(n) STOP 


Remarks: 


n is the number of the communications adapter 
(1 O82). 


A COM(n) ON statement must be executed to allow 
trapping by the ON COM(n) statement. If a 
nonzero line number is specified in the ON COM(n) 
statement, BASIC checks every time a new 
statement or line (depending on whether you 
compiled using /V, or /W) is executed to see if any 
characters have come in to the communications 
adapter. 


74 


COM(n) 
Statement 


If COM(n) is OFF, no event trapping takes place, 
and any communication activity is not remembered 
even if it does take place. When COM(n) is off, 
data is not lost unless the amount of data exceeds the 
size of the communications buffer. 


Note: If your program contains any 
event-trapping statements, such as ON COM, 
you need to compile your program using the /V 
or /W switch. 


If a COM(n) STOP statement has been executed, no 
trapping can take place. However, any 
communications activity that does take place is 
remembered so that an immediate trap occurs when 
COM(n) ON is executed. 
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COMMANDS 
Function 


Purpose: 


Versions: 


Format: 


Remarks: 
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Returns the parameters from the command line used 
to invoke the program. 


Cartridge Disk Advanced Compiler 


* KOK 


v$=COMMAND$ 


You can use this function to determine which 
command parameters are currently in effect. With 
this information you can verify, for example, the 
number of players selected for a game, and then 
branch to the appropriate section of code. 


All leading blanks are removed from the command 
line. The following characters, used to control 
redirection of I/O are also removed: 


< 
> 
o> 
| 


Anything following these characters is also removed. 
All letters are converted to uppercase (capital 
letters). 


Example: 


COMMANDS 
Function 


Suppose you have written a program named SORT, 
that sorts an input file alphabetically. If you invoke 
your program with the following: 


SORT TENNIS.NAM 


COMMANDS will return TENNIS.NAM to your 
program. You can then include a statement similar 
to the following in your SORT program: 


X$ = CHR$(34) + COMMAND$ + CHR$(34) 
OPEN X$ AS #1 


This procedure allows you to pass the name of the 


file you want to sort as a command parameter, rather 
than as input from the user during a program run. 


fit 


COMMON 
Statement 


Purpose: Passes variables to a chained or called program. ‘> 


Versions: Cartridge Disk Advanced Compiler 


Format: COMMON [SHARED ][/blockname/ variable|( || 
|, variable |[(Q]...] 


Remarks: 


SHARED _ allows you to share variables among all 
subprograms in a module. 


blockname is an identifier up to 31 characters long. 
the chained-to program. Arrays are 


specified by appending ‘‘()”’ to the array 
name. 


variable is the name of a variable to be passed to a 


BASIC Compiler 2.00 supports named common 
blocks, making it easier to pass information between 
subprograms and modules. 


Note: A standard COMMON, (blank 
COMMON) statement, becomes a named 
COMMON statement with the addition of the 
optional blockname parameter. 


The standard COMMON statement can be used for 
this purpose, but does not allow structured 
development of subprogram modules and libraries. 
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COMMON 
Statement 


There are two forms of array declaration in 
COMMON statements. If the array declaration uses 
the form: 


COMMON variable() 


the array is treated as a static array and must have 
been declared with integer constant subscripts in a 
previous DIM statement. 


If the array is declared using the following form: 
COMMON variable(integer) 


the array is treated as a dynamic array, where integer 
is an integer constant indicating the number of 
dimensions. The array elements are not allocated at 
this time; only space for the dynamic array descriptor 
is reserved in the COMMON area. (See ''How 
Variables Are Stored’ in BASIC Compiler 2.00 
Fundamentals for more information on the dynamic 
array descriptor.) The array must be allocated at 
some point by executing a DIM or REDIM statement 
referring to the array. If the array is allocated in the 
chaining program, it’s element values are passed to 
the chained-to program. The presence of a 
subsequent DIM statement in the chained-to 
program produces an error. Executing a subsequent 
REDIM erases the passed values. 


The SHARED attribute allows arrays to be shared 
globally by the main program and all subprograms 
within a module. To declare all variables as global 
variables, place the word ''SHARED" directly after 
the word ''DIM."' This differs from the SHARED 
Statement. The SHARED statement only affects 
variables within a single subprogram. For more 
information, see ““SHARED Statement.”’ 
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COMMON 
Statement 
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Unlike a blank COMMON statement, items in a 
named COMMON statement are not preserved 
across chaining to new programs. If the same 
blockname is used in more than one module, the 
variables in the variable list must be the same type 
and size and must be listed in the same order. 
However, the names may be different. For example: 


B.b.Et2) 
and 
E.F,G(2) 


is valid, but 


A.B. €(2) 
and 
E ;F(2).G 


is not. 


The COMMON statement must appear in a program 
before any executable statements. The 
nonexecutable statements for BASIC Compiler 2.00 
are: 


COMMON 

DEFtype 

DIM 

OPTION BASE 

REM 

All compiler metacommands. 


All other statements are executable. 


The DIM statement must appear before any 
COMMON statements. Also, if there are any 
variables in the COMMON statement whose types 
are defined by a DEFtype statement, the DEFtype 
statement must precede the COMMON statement. 


COMMON 
Statement 


When you use COMMON to communicate with a 
chained-to program, you must use the 
BASRUN20.EXE runtime module (compile without 
the /O parameter). Also, both the chaining program 
and the chained-to program require a COMMON 
statement. The order of variables in the two 
statements must be the same. The common variables 
must be common to a// programs you are chaining to. 
If the size of the COMMON in the chained-to 
program is smaller, the extra common variables are 
ignored. If the common size is larger, the additional 
common variables are initialized to zero or null. 


When you compile with the /O parameter, 
COMMON may only be used to pass variables to 
assembly language subprograms. To reference 
variables in COMMON, your assembly language 
subroutine needs this segment definition: 


COMMON SEGMENT COMMON ’BLANK’ 
and this group definition record: 
DGROUP GROUP COMMON 


A convenient way to share COMMON areas 
between programs is to place COMMON 
declarations and necessary preceding DIM 
statements in a single included file and use the 
$INCLUDE metacommand in each program. 
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COMMON 
Statement 


Examples: 
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For example: MENU.BAS 


100 REM $INCLUDE: ‘COMDEF' 


1000 CHAIN "PROGI" 


PROGI.BAS 


1100 REM $INCLUDE: ‘COMDEF' 


2000 CHAIN "MENU" 


COMDEF.BAS 


DIM A(1@@) ,B$(200) 
COMMON I,J K A() 
COMMON A$,B$(),X,Y,ZIP 


COMDEF.BAS shows how arrays are passed by 
adding () to the array name. 


This example chains to program PROG3 on the disk 
in drive A, and passes the static array D along with 
the variables A, BEE1, C, and G$. 


100 COMMON A,BEE1,C,D() ,G$ 
11@ CHAIN "A:PROG3" 


This is an example that uses dynamic arrays. 


100 COMMON X(2) “a 
110 REDIM X(N,M) 


YU Purpose: 


Versions: 


Format: 


Remarks: 


Example: 


COS 
Function 


Returns the trigonometric cosine function. 


Cartridge Disk Advanced Compiler 


of OK * KK 6 KOK 2 OK 


vy = COS(x) 


x is the angle whose cosine is to be calculated. 
The value of x must be in radians. To convert 
from degrees to radians, multiply the degrees 
by PI/180, where PI=3.141593. 


This example shows that the cosine of PI radians is 
equal to -1. Then it calculates the cosine of 180 
degrees by first converting the degrees to radians 
(180 degrees is the same as PI radians). 


19 PI=3.141593 

20 PRINT COS(PI) 

38 DEGREES=189@ 

40 RADIANS=DEGREES*P1/18@ 
5@ PRINT COS(RADIANS) 


Results: 


ach 
wy 
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CSNG 
Function 


Purpose: Converts x to a single-precision number. (> 


Versions: Cartridge Disk Advanced Compiler 
** K ** OK * OK ** KK 


Format: v = CSNG(x) 
Remarks: 


x is a numeric expression that is converted to 
single-precision. 


The rules outlined under ‘‘How BASIC Converts 
Numbers from One Precision to Another” in BASIC 
Compiler 2.00 Fundamentals are used for the 


conversion. ~ 


See also “‘CINT” and ‘““CDBL”’ functions for 
information on converting numbers to the integer 
and double-precision data types. 


Example: In this example, the value of the double-precision 
number A# is rounded at the seventh digit and 
returned as CSNG(A#). 


10 A# = 975.3421222# 
20 PRINT A#; CSNG(A#) 


Results: 


975.3421222 975.3421 
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YY Purpose: 


Versions: 


Format: 


Remarks: 


Example: 


CSRLIN 
Variable 


Returns the vertical coordinate of the cursor. 


Cartridge Disk Advanced Compiler 


7 OK KOK * OK OK 


v = CSRLIN 


The CSRLIN variable returns the current line (row) 
position of the cursor on the active page. The active 
page is explained under “SCREEN Statement.’’ The 
value returned is in the range 1 to 25. 


The POS function returns the column location of the 
cursor. See ‘‘POS Function.”’ 


See also ‘“‘LOCATE Statement’’ to see how to set the 
cursor line. 


This example saves the cursor coordinates in the 
variables X and Y, then moves the cursor to line 24 
to put the words “‘HI MOM” on that line. Then the 
cursor is moved back to its former position. 


10 Y = CSRLIN ‘record current line 
20 X = POS(@) ‘record current column 
30 LOCATE 24,1: PRINT "HI MOM" 

40 LOCATE Y,X ‘restore position 


CVI, CVS, CVD 
Functions 


Purpose: Converts string variable types to numeric variable 
types. 


Versions: Cartridge Disk Advanced Compiler 
** OK ** kK ok ** OK * KK 


Format: v = CVI(2-byte string) 
v = CVS(4-byte string) 
v= CVD(8-byte string) 


Remarks: Numeric values read from a random file must be 
converted from strings into numbers. CVI converts 
a 2-byte string to an integer. CVS converts a 4-byte 
string to a single-precision number. CVD converts 
an 8-byte string to a double-precision number. 


The CVI, CVS, and CVD functions do not change 
the bytes of the actual data. They change only the 
way BASIC interprets those bytes. 


See also ““MKI$, MKS$, MKD$ Functions,” as well 
as “BASIC Disk Input and Output,” in the BASIC 
Compiler 2.00 Fundamentals. 


86 


Example: 


CVI, CVS, CVD 
Functions 


This example uses a random file (#1) that has 
previously been opened, with fields defined as in line 
100. Line 110 reads a record from the file. Line 120 
uses the CVS function to interpret the first 4 bytes 
(N$) of the record as a single-precision number. N$ 
was probably originally a number that was written to 
the file using the MKS$ function. 


190 FIELD 71,4: ASS, 12:AS BS 


110 GET #1 
120 Y=CVS(N$) 
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DATA 


Statement 


Purpose: 


Versions: 


Format: 


Remarks: 
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Stores the numeric and string constants that are 
accessed by a program’s READ statements. 


Cartridge Disk Advanced Compiler 


* KOK 6 OK * KK KK 


DATA constant| ,constant|... 


constant can be a numeric or string constant. No 
expressions are allowed in the list. The 
numeric constants can be in any format 
— integer, fixed point, floating point, 
hex, or octal. String constants in DATA 
statements do not have to be enclosed 
by quotation marks, unless the string 
contains commas, colons, or significant 
leading or trailing blanks. 


DATA statements are nonexecutable and can be 
placed anywhere in the program. A DATA 
statement can contain as many constants as will fit 
on a line, and any number of DATA statements can 
be used in a program. The information contained in 
the DATA statements can be thought of as one 
continuous list of items, regardless of how many 
items are on a line or where the lines are placed in 
the program. The READ statements access the 
DATA statements in line-number order. 


The variable type (numeric or string) in the READ 
statement must agree with the corresponding 
constant in the DATA statement or a Syntax error 
occurs. 


DATA 
Statement 


You can use :REM to add a remark to a data 
statement. You cannot, however, use the single 
quote (’) to add remarks to the end of a DATA 
statement. If you do, the compiler thinks it is part of 
a string. 


Use the RESTORE statement to reread information 
from any line in the list of DATA statements. See 
““RESTORE Statement.”’ 


Example: See examples under ““READ Statement.”’ 
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DATES 
Variable and Statement 


Purpose: _ Sets or retrieves the date. 


Versions: Cartridge Disk Advanced Compiler 
* K ** oF kK * KK 


Format: As a variable: 
vs = DATE$ 
As a statement: 
DATE$ = x$ 
Remarks: _ For the variable (v§ = DATES): 


A 10-character string in the form mm-dd-yyyy is 
returned. Here, mm represents two digits for the 
month, dd is the day of the month (also two digits), 
and yyyy is the year. The date can have been set by 
DOS before running your application. 


For the statement (DATE$ = x$): 


x$ is a string expression used to set the current date. 
You can enter x$ in any one of the following forms: 


mm-dd-yy 
mm/dd/yy 
mm-dd-yyyy 
mm/dd/yyyy 
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Example: 


DATES 
Variable and Statement 


The year must be in the range 1980 to 2099. If you 
use only one digit for the month or day, a O (zero) is 
assumed in front of it. If you enter only one digit for 
the year, a zero is appended to make it two digits. If 
you enter only two digits for the year, the year is 
assumed to be 19yy. 


In this example we set the date to August 29, 1984. 
Notice how, when we read the date back using the 
DATES function, a zero is included in front of the 
month to make it two digits, and the year becomes 
1984. Also, the month, day, and year are separated 
by hyphens even though we enter them as slashes. 


10 DATE$="8/29/84" 
20 PRINT DATE$ 


Results: 


08-29-1984 
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DEF FN and END DEF and EXIT DEF 


Statements 
Purpose: Defines and names a function that you write. 
Versions: Cartridge Disk Advanced Compiler 
Format: First form 
DEF FNzaame|(arg [,arg]...) | =expression 
Second form 
DEF FNname|(arg [,arg]...)| 
[FNname = expression: EXIT DEF] 
FNname = expression 
END DEF 
Remarks: 
name is a valid variable name. This name, 
preceded by FN, becomes the name 
of the function. 
arg is an argument. It is a variable name 
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in the function definition that is 
replaced with a value when the 
function is called. The arguments in 
the list represent, on a one-to-one 
basis, the values that are given when 
the function is called. 


» 


DEF FN and END DEF and EXIT DEF 
Statements 


expression defines the returned value of the 
function. The type of the expression 
we) (numeric or string) must match the 
type declared by name. 


Note: Multiline function definitions (second 
form) are a new feature of this compiler. 
Single-line definitions (first form) are supported 
by all versions. 


The function definition can occupy one line, or as 
many program lines as required. If your function 
definition fits on a single program line, only the DEF 
FN statement is needed. 


Results must be assigned to the multi-line function 
name prior to leaving or ending the function, 
otherwise the results will be lost. 


Arguments (arg) that appear in the function 
definition serve only to define the function; they do 
not affect program variables that have the same 
name. A variable name used in the expression does 
not have to appear in the list of arguments. If it 
does, the value of the argument is supplied when the 
function is called. Otherwise, the current value of 
the variable is used. 


The function type determines whether the function 
returns a numeric or string value. The type of 
function is declared by name, in the same way as 
variables are declared. See ‘“‘How to Declare Variable 
Types” in BASIC Compiler 2.00 Fundamentals. If 
the type of expression (string or numeric) does not 
match the function type, a Type mismatch error 
occurs. If the function is numeric, the value of the 
expression is converted to the precision specified by 
name before it is returned to the calling statement. 
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DEF FN and END DEF and EXIT DEF 
Statements 
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A DEF FN statement must precede any reference to 
that function. If a function is called before it has 
been defined an Undefined user function error occurs. 
You can define a function only once. An attempt to 
redefine a function produces a (FD)Function 
definition error. 


Recursive functions are not supported. 


User defined functions cannot appear inside 
DEF/END DEF, IF/THEN/ELSE, FOR/NEXT, 
SUB/END SUB or WHILE/WEND blocks. 


Multiline Functions 


If your function definition occupies more than one 
program line you must begin the definition with a 
DEF FN statement, and end the definition with an 
END DEF statement. The EXIT DEF statement is 
available for branching out of the defined function. 


Because multiline functions are very powerful, they 
must be used with care. Some things to be aware of 
are: 


e The RETURN statement is not equivalent to the 
END DEF statement, or the EXIT DEF 
Statement. Using a RETURN statement in a 
multiline function can cause unpredictable 
results. 


DEF FN and END DEF and EXIT DEF 
Statements 


e If you are not careful when constructing 
multiline functions, you may get unexpected side 
effects. Most of these occur because, as an 
optimizing compiler, BASIC Compiler 2.00 may 
rearrange arithmetic expressions for greater 
efficiency. You should make use of temporary 
variables and parentheses to assure that 
expressions are evaluated in the intended order. 


Examples: In this example, line 20 defines the function 
FNAREA, which calculates the area of a circle with 
radius R. The function is called in line 40. 


1 Piss. 141593 
20 DEF FNAREA(R)=PI*RA2 


30 INPUT "Radius? ",RADIUS 
40 PRINT "Area is “ FNAREA(RADIUS) 


Results: 


Radius? 


(Suppose you respond with 2) 


Radius? 2 
Area is 12.56637 


DEF FN and END DEF and EXIT DEF 
Statements 


The following example converts a string to all 
uppercase or lowercase problems. 


200 DEF FNupper$(N$) 

210 REM FUNCTION TO CONVERT TO UPPER CASE 

220 LCASELET$="abcdefghijkImnopqrstuvwxyz" 

230 UCASELET$="ABCDEFGHIJKLMNOPQRSTUVWXYZ" 

240 L=LEN(N$) 

250 IF L = @ THEN FNupper$="": EXIT DEF 

260- POR A S240 Lb 

270 P=INSTR(LCASELET$ ,MID$(N$,I,1)) 

280 IF P <> @ THEN N$=MID$(N$,1,1-1)_ 
+MID$(UCASELET$,P,1)+MID$(N$,I+1,L-I+1) 

290 NEXT I 

300 FNupper$=N$ 

310 END DEF 


340 DEF FNlower$(N$) 

350 REM FUNCTION TO CONVERT TO LOWER CASE 

360 LCASELET$="abcdefghijk]mnopqrstuvwxyz-" 

370 UCASELET$="ABCDEFGHIJKLMNOPQRSTUVWXYZ" 

380 L=LEN(N$) 

390 IF L = @ THEN FNlower$='': EXIT DEF 

400 FOR I =11T0L 

410 P=INSTR(UCASELET$ ,MID$(N$,1,1)) 

420 IF P <> @ THEN N$=MID$(N$,1,1-1)_ 
+MID$(LCASELET$,P,1)+MID$(N$,I+1,L-I+1) 

430 NEXT I 

440 FNlower$=N$ 

450 END DEF 


480 REM MAIN PROGRAM 

490 A¢="abcdef12345ABCDE ! @#$%" 

500 B$=FNupper$(A$) 

510 C$=FNlower$(A$) 

520 IF B$ <> "“ABCDEF12345ABCDE! @#$%" _ 
THEN PRINT "UPPER CASE FAILED" 

530 IF C$ <> "“abcdef12345abcde! @#$%" _ 
THEN PRINT "LOWER CASE FAILED" > 

540 END 


& Purpose: 


Versions: 


Format: 


Remarks: 


DEF SEG 
Statement 


Defines the current segment of memory. A 
subsequent BLOAD, BSAVE, CALL ABSOLUTE, 
PEEK, POKE, or DEF USR definition specifies the 
offset into this segment. 


Cartridge Disk Advanced Compiler 
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DEF SEG [=segment]| 


segment iS a numeric expression in the range 0 to 
1048575. 


The initial setting for the segment when your 
application begins is the compiler’s data segment 
(DS). It is the beginning of your user workspace in 
memory. If you execute a DEF SEG statement that 
changes the segment, the initial setting is not restored 
when you issue a RUN command. 


If segment is given, it should be a value based upon a 
16-byte boundary, since segments begin only on 
paragraph boundaries. The value is shifted left 4 bits 
(multiplied by 16) to form the segment address for 
the subsequent operation. That is, if segment is in 
hexadecimal, zero is added to get the actual segment 
address. BASIC does not perform any checking to 
ensure that the segment value is valid. 


Note: DEF and SEG must be separated by a 
space; otherwise, BASIC interprets the 
statement DEFSEG=100 to mean “Assign the 
value 100 to the variable DEFSEG.”’ 
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DEF SEG 
Statement 


Any value entered outside the range indicated results 
in an Illegal function call error. The previous value is 
retained. 


See also “‘Calling Assembly Language Subprograms”’ 
in BASIC Compiler 2.00 Fundamentals for more 
information on using DEF SEG. 


Examples: The first example restores a segment to BASIC’s 
data segment. 


DEF SEG ' restore segment to BASIC's data segment 


In the second example, the screen buffer for the 
Color/Graphics Monitor adapter is at segment B800 
hex, offset 0. Since segments are specified on 
16-byte boundaries, the last hex digit can be dropped 
on the DEF SEG specification. 


DEF SEG=&HB800 -_ 
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Y Purpose: 


Versions: 


Format: 


Remarks: 


DEF type 
Statements 


Declares variable types as integer, single-precision, 
double-precision, or string. 


Cartridge Disk Advanced Compiler 


DEF type letter|-letter| |,letter |-letter]]... 


type is INT, SNG, DBL, or STR. 
letter is a letter of the alphabet (A-Z). 


A DEF»ppe statement declares that the variable 
names beginning with the letter or letters specified 
will be that type of variable. However, a 
type-declaration character (%, !, #, or $) always 
takes precedence over a DEFrype statement in the 
typing of a variable. See “‘How to Declare Variable 
Types” in BASIC Compiler 2.00 Fundamentals. 


If no type-declaration statements are encountered, 
the compiler assumes that all variables without 
declaration characters are single-precision variables. 


A DEF type statement takes effect as soon as it is 
encountered in your program during compilation. 
Once the type has been defined for the listed 
variables, that type remains in effect either until the 
end of the program or until another DEFtype 
Statement changes the type of the variable. Unlike 
the interpreter, the compiler cannot branch around 
the DEFdype statement (or any statement) by using a 
GOTO. 
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DEF type 
Statements 


Example: 


100 


Variables named with a type declaration character 
(%,!, #, or $;as in A%=B) are not affected by the 
DEFvype statement. 


For advanced programmers: 

DEFtype is not executable code. The compiler 
allocates memory for storage of the designated 
variables and assigns them to the correct data type. 


In this example, line 10 declares that all variables 
beginning with the letter L, M, N, O, or P are 
double-precision variables. 


Line 20 causes all variables beginning with the letter 
A to be string variables. 


Line 30 declares that all variables beginning with the 
letter X, D, E, F, G, or H are integer variables. ~ 


19 DEFDBL L-P 

20 DEFSTR A 

30 DEFINT X,D-H 

4Q ORDER = 1#/3: PRINT ORDER 

50 ANIMAL = "CAT": PRINT ANIMAL 
60 X=10/3: PRINT X 


Results: 


OR KS RR EK 6 oR RR ER 
CAT 
3 


© Purpose: 


Versions: 


Format: 


Remarks: 


DEF USR 
Statement 


Specifies the location in memory of an assembly 
language subroutine, which is later called by the USR 
function. 


Cartridge Disk Advanced Compiler 
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DEF USRI|n]=offset 


n must be a digit from 0 to 9. It identifies 
the number of the USR routine whose 
location in memory is being specified. If n 
is omitted, DEF USRO is assumed. 


of fset is an integer expression in the range 0 to 
1048575 The value of offset is added to 
the current segment value to obtain the 
actual starting address of the USR routine. 
See “DEF SEG Statement.” 


Any number of DEF USR statements can appear in a 
program, thus allowing access to as many subroutines 
as necessary. The most recently executed value is 
used for the offset. 
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DEF USR 
Statement 


Example: 
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This example loads an assembly language subroutine 
into an integer array. The n in line 60 is determined 
by the the total number of bytes in the subroutine 
divided by 2. 


19 OPTION BASE 1 

20 DEFINT A-Z 

58 ‘Dimension array for subroutine 

6@ DIM ARRAY (n) 

70 ‘Obtain offset of lst array element 
80 SUBRT = VARPTR(ARRAY(1)) 

99 ‘Load routine into the integer array 
199 BLOAD "ASMFILE" ,SUBRT 


1090 ‘Pass offset to DEF USR 
1910 DEF USR@ = SUBRT 

1920 ‘Execute the subroutine 
1030 J = USR@(I) 


YY Purpose: 


Versions: 
Format: 


Remarks: 


DIM 
Statement 


Specifies the maximum values for array variable 
subscripts and allocates storage accordingly. Also 
assigns the scope of a simple variable or array 
variable within a module. 


Cartridge Disk Advanced Compiler 


DIM [SHARED ]|variable 
| (subscripts )| |,variable| (subscripts)... 


SHARED allows you to share simple variables 
and arrays among all subprograms in 


a module. 

variable is the name of a simple variable or 
array and can be up to 40 characters 
in length. 

subscripts is a list of numeric expressions, 


separated by commas, which define 
the dimensions of the array. 


When executed, the DIM statement sets all the 
elements of the specified numeric arrays to an initial 
value of zero. String array elements are all variable 
length, with an initial null value (zero length). 


If an array variable name is used without a DIM 
Statement, the maximum value of its subscript is 
assumed to be 10. If a subscript is greater than the 
maximum specified, a Subscript out of range error 
occurs. 
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DIM 
Statement 


The minimum value for a subscript is always O unless 
otherwise specified with the OPTION BASE 
statement. (See “OPTION BASE Statement.’’) The ‘> 
maximum number of dimensions for an array is 60. , 
The maximum dimension value varies with the type 

of data stored in the array. Integer arrays, for 

example, can have a maximum dimension value of 

32766. 


An array that is dimensioned with a variable or 
expression is allocated dynamically. An array that is 
dimensioned with an integer constant is allocated 
Statically. 


The SHARED attribute allows variables to be shared 
globally by the main program and all subprograms 
within a module. To declare all variables as global 
variables, place the word ‘““SHARED” directly after 
the word ““DIM”’’. This differs from the SHARED 
Statement. The SHARED statement only affects 
variables within a single subprogram. For more 
information, see ‘“‘“SHARED Statement.”’ See also 
"STATIC Statement" for an example. 


You can redimension arrays that are declared 
dynamic. If you try to dimension any other type of 
array more than once, a Duplicate definition error 
occurs. 


For more information on redimensioning arrays see 
''ERASE Statement,’ ““REDIM Statement,” 
“SDYNAMIC Statement.” and “$STATIC 
Statement,” See also ''Data Types" in BASIC 
Compiler 2.00 Fundamentals. 
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DIM 
Statement 


Example: The following example performs the multiplication of 
2 arithmetic arrays and assigns the product to a third 
array. The accompanying diagram illustrates this 
process. 


138 DIM A(4,2), B(2,4), C(4,4) 
149 FOR I = 1 T0 4 
Poy. FOR: K =a 


169 READ A(I,K) 
17/@ NEXT K 

180 NEXT I 

199 FOR K=1 10 2 

200 FOR J = 1 T0 4 
210 READ B(K,J) 
220 NEXT J 

230 NEXT K 

240 FOR I = 1 TO 4 

208 FOR J =1 10 4 
260 FOR K = 1 10 2 
270 C(I J): Sea  BCK yd). C(I 0) 
280 NEXT K 

290. NEXT 

3008 NEXT I 

31@ CLS 


320 FOR I = 1 T0 4 

330°: -- LOCATE: Tat 

340 FOR J = 1 70 4 

359 PRINT: Clicods 

360 NEXT J 

378 NEXT I 

38@ END 

399 REM MATRIX A 

400 DATA 8,3,4,2,5,6,19,12 
418 REM MATRIX B 

420 DATA 9,11,13,15,5,6,4,8 


DIM 
Statement 
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YY Purpose: 


Versions: 


Format: 


Remarks: 


DRAW 
Statement 


Draws an object as specified by string. 


Cartridge Disk Advanced Compiler 


Graphics mode only. 
DRAW string 


The DRAW statement draws objects using a graphics 
definition language. The language commands are 
contained in the string expression string. The string 
defines an object, which is drawn at execution time. 
When a movement command is given, a line is drawn 
from the last point referenced. 


In the following movement commands, n indicates 


the distance to move. The number of points moved 
is n times the scaling factor (set by the S command). 


The movement commands are detailed on the next 
page. 


DRAW 


Statement 

Un Move up. 

Dn Move down. 

Ln Move left. 

Rn Move right. 

En Move diagonally up and right. 

Fn Move diagonally down and right. 

Gn Move diagonally down and left. 

Hn Move diagonally up and left. 

M x,y Move absolute or relative. If x has a plus 
sign (+) or a minus sign (-) in front of it, 
it is relative. Otherwise, it is absolute. ~ 
The following two prefix commands can 
precede any of these movement 
commands: 

Move, but don’t plot any points. 
N Move, but return to the original position 


when finished. 
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DRAW 
Statement 


The following commands are also available: 


An 


TAn 


Set angle n. The value of n can range 
from 0 to 3, where 0 is O degrees, | is 90, 
2 is 180, and 3 is 270. Figures rotated 90 
or 270 degrees are scaled so they appear 
the same size with 0 or 180 degrees on a 
display screen with standard aspect ratio 
4/3. 


Turn angle n. The value of n can range 
from -360 to +360. If 7 is positive (+), 
the angle turns counterclockwise. If n is 
negative (-), the angle turns clockwise. 
Values entered that are outside of the 
range -360 to +360 cause an Illegal 
function call error. 


Set color n. n is an integer that specifies a 
color attribute. In SCREEN 1 (medium 
resolution), m can range from 0 to 3. In 
SCREEN 2 (high resolution), n can be O 
ort. 


The default color attribute for the 
foreground is the maximum color attribute 
for that screen mode. 


The default color attribute for the 
background is always zero. 
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DRAW 
Statement 


Sn Set scale factor. The value of nm can range 
from 1 to 255. The scale factor is n 
divided by 4. For example, if n=1, then 
the scale factor is 1/4. The scale factor 
multiplied by the distances given with the 
U, D, L, R, E, F, G, H, and relative M 
commands gives the actual distance 
moved. The default value is 4, so the scale 
factor is 1. 


110 


DRAW 
Statement 


X variable; 
Execute substring. This allows you to 
& execute a second string from within a 
string. 


You must use the VARPTR$ format for 
this command, as follows: 


“XX” + VARPTRS$ (variable) 


Unlike the interpreter, the compiler does 
not allow trailing semicolons in the 
command string. 


P paint,boundary 
Set figure color to paint and border color 
to boundary. The paint parameter is an 
integer expression. You select this 
attribute from the attribute range for the 
wy current screen mode. 


The boundary parameter is the border 
color attribute of the figure to be filled in. 
You select this attribute from the attribute 
range for the current screen mode. In 
SCREEN 1, (medium resolution), attribute 
can range from 0 to 3. In SCREEN 2, 
(high resolution), attribute can be O or 1. 
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DRAW 
Statement 


i 


The default color attribute for the 
foreground is the maximum color attribute 
for that screen mode. For example, in 
SCREEN 5, the default color attribute is 
is: 


The default color attribute for the 
background is always zero. 


DRAW 
Statement 


There are two ways you can specify variables in a 
PLAY or DRAW string for the compiler: 


e Use the ‘‘X”’ variable form, concatenated (‘‘+’’) 
with the VARPTR$ of the variable itself. 


e Use the DRAW or PLAY macro, followed by an 
equal sign (=) and concatenated (‘‘+’’) with the 
VARPTRS$ of the variable itself. 


The following examples demonstrate both 
methods. 


You must use the VARPTRS$ form for variables. For 
example: 


Interpreter Method Compiler Method 


DRAW "XA$;" DRAW "X"+VARPTRS$(A$ 
DRAW "S=SC;" DRAW “S="+VARPTR$(S 


) 

9) 

The X command can be a very useful part of 

DRAW. It allows you to define segments of a 
picture in different X variables and to combine these 
X variables into a single DRAW statement. For 
example, if you are creating a scene of a house with a 
chimney and a tree, each of these objects can be 
defined in an X variable so your DRAW statement 
can look like this: 


DRAW "X"+VARPTR$(HOUSE$)+°X" _ 
+VARPTR$(CHIM$)+"X"+VARPTR$(TREE$ ) 
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DRAW 


Statement 
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The aspect ratio of your screen determines the 
spacing of the horizontal, vertical, and diagonal 
points. The DRAW statement does not take into “Aa 
account the aspect ratio of the current screen mode; : 
that is, DRAW “R50 U50” plots exactly 50 points to 

the right and then 50 up, but the two lines will not 

appear to be equal in length. 


The aspect ratio is used to correct the shape of 
objects drawn on a nonlinear surface. The idea is to 
be able to draw a square, for example, that indeed 
looks square. 


If there are 640 by 640 dots on a screen evenly 
spaced along the x and y axes, the aspect ratio is ‘1 
to 1” or 1/1. This is an ideal surface. If you execute 
the statement: 


DRAW "R100 D190 L100 U190" ~ 


the box appears square. 


The compiler, however, only supports three screen 
resolutions, each with its own aspect ratio. These 
are: 


Resolution Aspect Ratio 


High resolution 640 by 200 dots 5/12 


320 by 200 dots 


Examples: 


DRAW 
Statement 


To draw a box that appears square in any resolution, 
scale the y axis by the corresponding aspect ratio; or 
scale the x axis by 1 /aspect ratio. 


For example, to draw a square box 100 high, scale 
the x axis as follows: 


19 '100*6/5 is 120 
20 DRAW "U190 R120 D19G L120" 


To draw a box using variables: 


10 SCREEN 1 

20 A=20 

30 DRAW "U="+VARPTR$(A)+"R="+VARPTR$(A)+_ 
"D="+VARPTR$(A)+"L="+VARPTR$(A) 

49 ' DUMMY TIMING LOOP 

5@ FOR I=1 TO 10000: NEXT I 


To draw a box and paint the interior: 


5). SEGRE Cad 

10 DRAW "U5@R5@D5@L50" ‘Draw a box 

20 DRAW "BE1Q@" ‘Move up and right into box 
30 DRAW "P1,3" ‘Paint interior 

40 ° DUMMY TIMING LOOP 

50 FOR I=1 TO 10000: NEXT I 


To draw a triangle: 


1Q@ SCREEN 1 

20 DRAW "E15 F15 L3Q" 

30 ' DUMMY TIMING LOOP 

40 FOR I=1 TO 10000: NEXT I 
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DRAW 
Statement 


To create a “shooting star”’: 


Pe SCREEN Jd 50: COLOR 9,0: CLS ‘> 
20 DRAW "BM3@@0,25" ° initial point 

De SIARS=  Mt7 sty? Met 2eeed2 Mt+20 0 M-17 12: Mey s-l7 

40 FOR SCALE=1 TO 4@ STEP 2 

50 DRAW "C1;S="+VARPTR$(SCALE )+°BM-2 ,0;X"+VARPTR$(STAR$) 

60 NEXT 


To draw some spokes: 


#U-SCREEN 1,90:CLS 

20 FOR D=@ TO 360 STEP 1@ 

30 DRAW "TA="+VARPTR$(D)+"NU5Q" 
40 NEXT D 
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YY Purpose: 


Versions: 


Format: 


Remarks: 


YY Example: 


END 
Statement 


Terminates program execution, closes all files, and 
returns to command level. 


Cartridge Disk Advanced Compiler 


* KOK OK KK OK 


END 


END statements can be placed anywhere in the 
program to terminate execution. 


An END statement at the end of a program is 
optional. The compiler always returns to DOS after 
an END is executed, and resets the screen to the 
initial screen mode. 


This example ends the program if K is greater than 
1000; otherwise, the program branches to the label 
SyLAKT,.. 


190 IF K>1@@@ THEN END ELSE GOTO START 
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ENVIRON 


Statement 
Purpose: Modifies parameters in BASIC’s environment table. 
Versions: Cartridge Disk Advanced Compiler 
mere ee ek 
Format: ENVIRON string 
Remarks: _ string is of the form: 
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‘“parm| = |[text][ ;]” 


parm is the name of the parameter, such as 
“PATH.” 

text is a String expression that defines the new 
parameter. 


parm must be separated from fext by an 
equal sign or a blank. ENVIRON takes 
everything left of the first blank or equal 
sign as parm. The first “‘nonblank, 
nonequal”’ after parm is taken as the 
beginning of fext. 


If string is a null string or consists only of 


6699 


;’’ (a single semicolon), such as: 
"PATH=; " 


the parameter is removed from the 
environment table and the table is 
compressed. 


If parm does not exist, the new parameter “Oo 
is added at the end of the environment 
table. 


Example: 


ENVIRON 
Statement 


If parm exists, it is deleted, the 
environment table is compressed, and 
parm is added at the end. 


Note: When your compiled program 
is invoked, the size of its environment 
table is the current size of DOS’s 
environment table (rounded up to the 
next 16-byte paragraph boundary.) 
Your program cannot expand its 
environment table. If you wish to add 
elements to the environment table, 
you must expand the table from DOS 
to the size your application needs 
before invoking your BASIC 
program. 


ENVIRON is used to pass configuration parameters, 
such as a path specification, to a child process 
invoked using SHELL; or to pass configuration 
parameters to your application from the DOS 
environment. 


You can create a default PATH to the root directory 
on drive A with the following statement: 


ENVIRON "PATH=A: \" 


Now, you can invoke DOS from your BASIC 
program using the SHELL statement and issue any 
valid DOS command. If a disk file is needed to 
execute the command, DOS now automatically 
searches for it (COM, .EXE, or .BAT) in the root 
directory on drive A if it is not on the current drive 
or directory. 
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Statement 
SHELL ‘Invokes a copy of COMMAND.COM. 
B> REM Change directory to "WORK" on drive B. (‘> 
B> CD B: \WORK 


B> REM Loads PROJ1 under DEBUG 
B> DEBUG PROJ1 


B> REM Return to BASIC program 
B> EXIT (exit DOS, return to BASIC program. ) 


You can add a new parameter to the environment 
table: 


ENVIRON "HELP = C:\HELP" ‘defines 


file parameter called "HELP" 
CHDIR ENVIRON$ ("HELP") ‘changes dir to "HELP" 


You can delete this parameter in the table by: “ 


ENVIRON "“HELP=;" ‘deletes parameter “HELP” 
from table 


Note: For related information, see also 
‘“ENVIRON$ Function” and ‘SHELL 
Statement” in this manual. Also “SET 
Command” in Disk Operating System Reference, 
and the ‘“‘EXEC Function Call” in Disk 
Operating System Technical Reference. 
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Y Purpose: 


Versions: 


Format: 


Remarks: 


ENVIRONS 
Function 


Retrieves the specified string from BASIC’s 
environment table. 


Cartridge Disk Advanced Compiler 


* KK 2 OK OK 


v$ = ENVIRONS (parm$) 
or 
v$ = ENVIRONS (n) 


parm$ is a string containing the 
parameter to be retrieved. 


n is an integer expression returning 
a value in the range 1 to 255. 


If a string argument is used, ENVIRONS$ returns, 
from the environment table, a string containing the 
text that follows parm$. If parm$ is not found or no 
text follows the equal sign, the null string is returned. 


If a numeric argument is used, ENVIRONS$ returns a 
string containing the nth parm$ from the 
environment table, along with the parm$= text. If 
there is no nth parm, a null string is returned. 
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ENVIRONS 
Function 


Examples: 
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ENVIRONS$ distinguishes between uppercase letters 
and lowercase letters. If you add to the table in this 
format: ‘> 


ENVIRON “load = high" 


and want to check to see if the operation was 
successful, you can use the ENVIRON$ function like 
this: 


PRINT ENVIRONS ("load") 
But if you execute: 
PRINT ENVIRON$ ("LOAD") 


ENVIRONS returns a null string because ‘“‘LOAD”’ 
is not in the table; however, “‘load”’ is in the table. 


Note: All parameters entered into the 
environment are converted to uppercase by 
DOS. 


When DOS loads initially, it sets a parameter called 
‘““COMSPEC” that tells DOS where to locate the 
COMMAND.COM file, and it sets up a null path. 
To observe the contents of the environment table at 
start-up time, execute the following from your 
program. 


PRINT ENVIRONS (1) 
PRINT ENVIRONS (2) 


Results: 


PATH= “a 
COMSPEC = A: \COMMAND.COM 


ENVIRONS 
Function 


Note: If you booted from a fixed disk, the 
previous example displays C: instead of A: for 
the drive specification. 


If you execute: 

PRINT ENVIRON$ ("COMSPEC" ) 
the computer’s response is: 

A: \COMMAND.COM 


The following program saves the compiler’s 
environment table in an array so that it can be 
modified for a child process. After the child process 
is completed, the environment is restored. 


10 DIM TABLE$(1@) ‘assume no more than 19 parms 
20 PARMS = 1 ‘initial number of parameters 
3@ WHILE LEN(ENVIRON$(PARMS)) > @ 
40 TABLE$(PARMS) = ENVIRON$(PARMS ) 
5Q@ PARMS = PARMS+1 
6@ WEND 
7@ PARMS = PARMS - 1 ‘adjust to correct number 
88 ‘now store new environment 
90 ENVIRON "DATAIN = C: \DATAIN\ INP.FIL" 
190 ENVIRON "SORT.DAT = SORT<" + 
ENVIRON$ ("DATAIN") +°>LPT1:" 


1908 SHELL ENVIRON$("SORT.DAT") ‘data is sorted 
1010 FOR I = 1 TO PARMS 

1020 ENVIRON TABLE$(I) ‘restore parameters 
1030 NEXT I 
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ENVIRONS 
Function 


Note: See also “ENVIRON Statement” and 
“SHELL Command.” Also “SET Command” in 

Disk Operating System Reference and “EXEC (> 
Function Call’ in Disk Operating System 
Technical Reference. 
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Y Purpose: 


Versions: 


Format: 


Remarks: 


EOF 
Function 


Indicates an end-of-file condition. 


Cartridge Disk Advanced Compiler 
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v = EOF(filenum) 


filenum _ is the number specified on the OPEN 
statement. 


The EOF function is useful for avoiding an Input past 
end error. EOF returns -1 (true) if end of file has 
been reached on the specified file. A zero is 
returned if end of file has not been reached. 


EOF is significant only for a file opened for 
sequential input from disk or cassette, or for a 
communications file. A -1 for a communications file 
means the buffer is empty. If you attempt to GET a 
record from beyond the end of a random access file, 
EOF is still false and no error is detected, but a null 
record is returned. 


EOF(O) returns the end-of-file condition on 
standard input devices used with redirection of I/O. 


EOF 
Function 


Example: This example reads information from the sequential 
file named “DATA.” Values are read into the array 
M until end of file is reached. ‘> 


10 OPEN "DATA" FOR INPUT AS #1 
20 C=0 

30 IF EOF(1) THEN END 

40 INPUT #1,M(C) 

59 C=C+1: GOTO 39 
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YY Purpose: 


Versions: 


Format: 


Remarks: 


ERASE 
Statement 


Removes or resets the elements of an array. 


Cartridge Disk Advanced Compiler 


ERASE arrayname|,arrayname]... 


arrayname is the name of the array you want to 
erase or reset. 


The ERASE statement performs differently for static 
and dynamic arrays. When an ERASE statement is 
executed on a Static array, the array elements are set 
to either zeroes or null strings. Executing an ERASE 
on a dynamic array deallocates the array elements. 
Before making another reference to the dynamic 
array you must first redimension it using either a 
DIM or REDIM statement. 


You may want to use the ERASE statement if you 
are running short of storage space while running a 
program. After dynamic arrays are erased, the space 
in memory allocated for the arrays can be used for 
other purposes. 


ERASE must be used when you want to redimension 
arrays in your program. If you try to redimension an 
array without first erasing it, a Duplicate definition 


error OCCUurs. 


ERASE 


Statement 


Example: 


128 


If an array is declared dynamic inside a subprogram, 
that array will still exist after you exit the 
subprogram. This causes an error if you call the (‘> 
subprogram a second time and again declare it. To 

avoid this, use ERASE to deallocate the array before 

you EXIT the subprogram. 


The CLEAR command erases ai// variables from the 
work area. 


This example uses the FRE function to show how 
ERASE can be used to free memory. The array BIG 
used up about 40K bytes of memory when it was 
dimensioned as BIG(100,100). After it was erased, 
it could be redimensioned to BIG(10,10). 


199 '$DYNAMIC 

119 START=FRE(-1) 

120 DIM BIG(199,199) 

130 MIDDLE=FRE(-1) “ 
149 ERASE BIG 
159 REDIM BIG(19,19) 

169 FINAL=FRE(-1) 

179 PRINT START, MIDDLE, FINAL 


Results: 


415168 374336 414656 


Ww Purpose: 


Versions: 


Format: 


Remarks: 


ERDEV and ERDEVS$ 
Variables 


Read-only variables. Hold the INTerrupt 24 error 
code of a device error and the name of the device 
generating the error. 
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** KK ** KK OK 


vy = ERDEV 


ERDEYV is a read-only variable. When a critical 
error is detected, ERDEV holds the DOS INTerrupt 
24 error code in the lower 8 bits, and the upper 8 bits 
contain bits 13, 14, and 15 of the attribute word of 
the device header block. 


ERDEVS$ is a read-only variable. If the error was on 
a character device, ERDEV$ contains the 8-byte 
character device name. If the error was not ona 
character device, ERDEV$ contains the two- 
character block device name (A:, B:, C:, etc.). 


ERDEV and ERDEVS 
Variables 


Examples: 


This example simulates a printer error. 


1 CLS 

20 ON ERROR GOTO 60 

30 LPRINT'The printer is ready" 
40 PRINT'The printer is ready" 
5@ END 

60 V$=HEX$(ERDEV) 

7@ PRINT “ERDEV = "3V$ 

80 D$=ERDEV$ 

90 PRINT “ERDEV$ = ";D$ 

100 RESUME NEXT 


If you run this example with the printer turned off, 
the computer displays: 


ERDEV = 8009 


ERDEV$ = LPT1 ~ 


Note: If you are using a printer other than the 
IBM Graphics Printer, you may receive a 
different error code. 


The lower 8 bits (bits 0-7) of the binary equivalent 
equal 9, which is the INT24 error code for Printer 
out of paper. The meaning of bits 13, 14, and 15 of 
the value returned by ERDEV is explained in the 
section “‘Attribute Field’’ of Disk Operating System 
Technical Reference under “Installable Device 
Drivers.” 


See also "IOCTL Statement" and ''TOCTL$ 
Function." 
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Ww Purpose: 


Versions: 


Format: 


Remarks: 


ERR and ERL 
Variables 


Return the error code and line number associated 
with an error. 
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* ok * ok * KK * KOK 
v= ERR 
v= ERL 


The variable ERR contains the error code for the last 
error. 


If line numbers are used, ERL returns the number of 
the last line executed before the error was detected. 
If line numbers are not used, ERL returns 0. The 
ERR and ERL variables are usually used in 

IF... THEN statements to direct program flow in the 
error-handling routine. See “ON ERROR 
Statement.” 


If you test ERL in an IF...THEN statement and you 
are using the interpreter as an editor, be sure to put 
the line number on the right side of the relational 
operator, like this: 


IF ERL = line number THEN ... 


ERR and ERL can be set using the ERROR 
statement (see next entry). 


Compiler error codes are listed in Appendix A, 
‘““Error Messages.” 
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ERR and ERL 
Variables 


Example: This example tests to see if the drive door is open 
when the program needs to open a file. (‘> 


19 ON ERROR GOTO 1090 
20 OPEN "DATA" FOR INPUT AS #1 
3% END 


100 IF ERR=71 THEN LOCATE 23,1: 
PRINT "DISK IS NOT READY":RESUME 
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Purpose: 


Versions: 


Format: 


Remarks: 


ERROR 
Statement 


Simulates the occurrence of a BASIC error or allows 
you to define your own error codes. 


Cartridge Disk Advanced Compiler 


2K ok * kK * KK * KK 
ERROR n 
n must be an integer expression between 1 and 
ZOD. 


If the value of n is the same as an error code used by 
BASIC (see Appendix A, “‘Error Messages’’), the 
ERROR statement simulates the occurrence of that 
error. If an error-handling routine has been defined 
by the ON ERROR statement, the error routine is 
entered. Otherwise, the error message corresponding 
to the code is displayed, and execution halts. See the 
first example. 


Note: If your program contains any ON 
ERROR or RESUME statements, you need to 
compile using the /X or /E parameter. See 
‘‘Compiler Parameters” in BASIC Compiler 
2.00 Fundamentals for more information. 


To define your own error code, use a value that is 
different from any used by BASIC. (We suggest you 
use the highest available values; for example, values 
greater than 200.) This new error code can then be 
tested in an error handling routine, just like any other 
error. See the second example. 


ERROR 
Statement 


If you define your own code in this way, and you 
don’t handle it in an error handling routine, the 
message Unprintable error appears and execution 
halts. 


Examples: The first example simulates a String formula too 
complex error. 


10 - Ts 10 
20 ERROR T 


Results: 
String formula too complex in line 2@ 


The next example is a part of a game program that 

allows you to make bets. An error code of 210 is 

chosen because it is normally unused. The program 

traps the error if you exceed the house limit. ~ 


108 ON ERROR GOTO 1000 
11@ INPUT "WHAT IS YOUR BET" ;B 
120 IF B > 5@@@ THEN ERROR 219 


1000 IF ERR = 210 THEN PRINT 
"HOUSE LIMIT IS $5000" 
1019 IF ERL = 120 THEN RESUME 110 


Note: If your program uses error trapping 
statements, you must compile it with the /D 
parameter. 
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Purpose: 


Versions: 


Format: 


Remarks: 


Example: 


EXP 
Function 


Calculates the exponential function. 
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OK OK * OK ** K 


v = EXP(x) 

x can be any numeric expression. 

This function returns the mathematical number e 
raised to the x power. e is the base for natural 


logarithms. An overflow occurs if x is greater than 
88.02969. 


This example calculates e raised to the (2-1) power, 
which is simply e. 


10% iS 22 
20 PRINT EXP(X-1) 


Results: 


2.118282 
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FIELD 


Statement 
Purpose:  Allocates space for variables in a random file buffer. 
Versions: Cartridge Disk Advanced Compiler 
* KK * KK * KOK * ok 
Format: FIELD [#|filenum, width AS stringvar [|,width AS 
stringvar)... 
Remarks: 
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filenum is the number under which the file was 
opened. 
width is a numeric expression specifying the 


number of character positions to be 
allocated to stringvar. 


stringvar is a String variable that is used for 
random file access. 


A FIELD statement defines variables used to get 
data out of a random buffer after a GET or to enter 
data into the buffer for a PUT. 


The statement: 
FIELD 1, 20 AS N$, 10 AS ID$, 4@ AS ADD$ 


allocates the first 20 positions (bytes) in the random 
file buffer to the string variable N$, the next 10 
positions to ID$, and the next 40 positions to ADD$. 
FIELD does not actually place any data into the 
random file buffer. This is done by the LSET and 
RSET statements. See ‘““LSET and RSET 
Statements.”’ 


FIELD 
Statement 


FIELD does not ‘‘remove’’ data from the file either. 
Information is read from the file into the random file 
buffer with the GET (file) statement. Information is 
read from the buffer by simply referring to the 
variables defined in the FIELD statement. 


The total number of bytes allocated in a FIELD 
statement must not exceed the record length 
specified when the file was opened. Otherwise, a 
Field overflow error occurs. 


Any number of FIELD statements can be executed 
for the same file number, and all FIELD statements 
that have been executed are in effect at the same 
time. Each new FIELD statement redefines the 
buffer from the first character position, so this has 
the effect of having multiple field definitions for the 
same data. 


Note: Be careful about using a fielded variable 
name in an input or assignment statement. Once 
a variable name is defined in a FIELD 
statement, it points to the correct place in the 
random file buffer. If a subsequent input 
statement or LET statement with that variable 
name on the left side of the equal sign is 
executed, the variable is moved to string space 
and is no longer in the file buffer. This can be 
avoided by assigning the input to a temporary 
variable, then using LSET or RSET to move the 
input into the variable declared in the FIELD 
statement. 


See ““BASIC Disk Input and Output’? and Appendix 
D, “‘Using IBM Personal Computer ISAM Files”’ in 
the BASIC Compiler 2.00 Fundamentals for a 
complete explanation of how to use random files. 
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FIELD 


Statement 


Examples: 
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This example opens a file named ““CUST” as a 
random file. The variable CUSTNOS$ is assigned to 
the first two positions in each record, CUSTNAME$ 
is assigned to the next 30 positions, and ADDR$ is 
assigned to the next 35 positions. 


Lines 30 through 50 put information into the buffer, 
and the PUT statement in line 60 writes the buffer to 
the file. Line 70 reads back that same record, and 
line 90 displays the three fields. Note in line 80 that 
it is permissible to use a variable name that was 
defined in a FIELD statement on the right side of an 
assignment statement. 


10 OPEN ‘A:CUST" AS #1 

20 FIELD 1, 2 AS CUSTNO$, 3@ AS CUSTNAME$, 
35 AS ADDR$ 

30 LSET CUSTNAME$= "O'NEIL INC" 

QQ LSET AGDRS= “50 SE 12TH :ST, NY, NY 

50 LSET CUSTNO$=MKI$(785@) 

6p Put at 

7Y: GE 2,1 

80 CNUM%= CVI(CUSTNO$): N$ = CUSTNAME$ 

99 PRINT CNUM%, N$, ADDR$ 


The program below shows two different ways to 
retrieve information from the same random file. The 
contents of the file do not change. 


10 OPEN "PROG" AS #1 
20 FIELD 1, 20 AS LASTNAME$,15 AS FIRSTTWO$ 
30 FIELD 1, 34 AS WHOLENAME$, 1 AS INITIAL$ 


vY Purpose: 


Versions: 


Format: 


Remarks: 


FILES 
Command 


Displays the names of files residing on a disk. The 
FILES command in BASIC is similar to the DIR 
command in DOS. 


Cartridge Disk Advanced Compiler 


OK > OK * KOK KK 


FILES [filespec| 


filespec is a String expression for the file 
specification. It can contain a path and 
must conform to the rules outlined 
under ‘“‘Naming Files” in BASIC 
Compiler 2.00 Fundamentals, otherwise, 
a Bad file name error occurs. 


If filespec is omitted, all the files on the 
current directory of the DOS default 
drive are listed. 


All files matching the filename are displayed. The 
filename can contain question marks (?). A question 
mark matches any character in the name or 
extension. An asterisk (*) in any character position 
matches any and all characters from that position on. 
If a drive is specified as part of filespec, files that 
match the specified filename on the current directory 
of that drive are listed. Otherwise, the DOS default 
drive is used. 
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FILES 
Command 


Examples: This command displays all files on the current 
directory of the DOS default drive. 


FILES ‘> 


This displays all files with an extension of .BAS on 
the current directory of the DOS default drive. 


PILES" Seas. 
This displays all files on drive B. 
PILES: Sh. 


Another way to list all the files on the current 
directory of drive B is: 


PLCS 2s - 


This lists each file on the current directory of the =) 
DOS default drive that has a filename beginning with 

TEST followed by up to two other characters, and an 
extension of .BAS. 


PELES 457 te BAS” 


In addition to listing all the files, the current 
directory name and the number of bytes free are also 
displayed. 


When using tree-structured directories, remember 

that each subdirectory contains two special entries. 

They are listed when you use the FILES command to 

list a subdirectory. The first contains a single period 
instead of a filename. It identifies this ‘“‘file’’ as a 
subdirectory. The second entry contains two periods Ss 
instead of a filename. It locates the higher level 

directory that defines this subdirectory. 
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FILES 
Command 


See ‘“‘Input and Output” in BASIC Compiler 2.00 
Fundamentals for more information on tree 
structured directories. 


This example lists all files in the current subdirectory 
called LEVEL1 on drive A. Note that the directory 
is empty. 


PIEES: OA: \LEVEiee 
<DIR> ex =D I R> 
32824 Bytes free 


The FILES command can also be used to list files in 
other directories. The example below lists all files in 
the subdirectory LVL1. The backslash must be used 
after the directory name. 


PILES: <"EVEE Ne 


This example lists all files in the directory LVL2 
with an extension of .BAS. 


FIEES. ““LVG2 \ 2a 
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FIX 


Function 


Purpose: 


Versions: 


Format: 


Remarks: 


Examples: 
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Truncates x to an integer. 


Cartridge Disk Advanced Compiler 


OK 6 KOK 6 OK 6 OK 


v = FIX(x) 
x can be any numeric expression. 


FIX strips all digits to the right of the decimal point 
and returns the value of the digits to the left of the 
decimal point. 


The difference between FIX and INT is that FIX 
does not return the next lower number when x is 
negative. 


See the “INT” and “‘CINT” functions, which also 
return integers. 


Note in the examples how FIX does not round the 
decimal part when it converts to an integer. 


PRINT FIX(45.67) 


Results: 


45 


PRINT FIX(-2.89) 


Results: 


“2 


Y Purpose: 


Versions: 


Format: 


Remarks: 


FOR and NEXT 
Statements 


Performs a series of instructions in a loop a given 
number of times. 
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FOR variable=x TO y [STEP z] 


NEXT [ variable | variable}... | 


variable is an integer or single or 
double-precision variable to be used as a 
counter. 

x is a numeric expression that is the initial 


value of the counter. 


y is a numeric expression that is the final 


value of the counter. 


z is a numeric expression to be used as an 


increment. 


The program lines following the FOR statement are 
executed until the NEXT statement is encountered. 
Then the counter is incremented by the amount 
specified by the STEP value (z). If you do not 
specify a value for z, the increment is assumed to be 
1. A check is performed to see if the value of the 
counter is now greater than the final value y. If it is 
not greater, BASIC branches back to the statement 
after the FOR statement and the process is repeated. 


FOR and NEXT 
Statements 


If it is greater, execution continues with the 
statement following the NEXT statement. This is a 
FOR...NEXT loop. ‘> 


If the value of z is negative, the test is reversed. The 
counter is decremented each time through the loop, 
and the loop is executed until the counter is less than 
the final value. 


The body of the loop is skipped if x is already greater 
than y when the STEP value is positive, or x is less 
than y when the STEP value is negative. If z is zero, 
an infinite loop is created unless you provide some 
way to set the counter greater than the final value. 


If you compile with the /D parameter, all loops will 
execute at least once. 


Program performance improves if you use integer ~ 
counters whenever possible. 
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FOR and NEXT 
Statements 
Nested Loops 


FOR...NEXT loops can be nested; that is, one 
FOR...NEXT loop can be placed inside another 
FOR...NEXT loop. When loops are nested, each 
loop must have a unique variable name as its counter. 
FOR...NEXT loops must be nested physically as well 
as logically; that is, the NEXT statement for the 
inside loop must appear before that for the outside 
loop. 


Note: If nested loops have the same end point, 
a single NEXT statement can be used for all of 
them. This is different from the interpreter. 


A NEXT statement of the form: 
NEXT varl,. Vard.  ¥eeseies 
is equivalent to the sequence of statements: 


NEXT varl 
NEXT var2 
NEXT var3 


The variable(s) in the NEXT statement can be 
omitted, in which case the NEXT statement matches 
the most recent FOR statement. It is a good idea 
always to include the variables to avoid confusion, 
but it can be necessary if you do any branching out 
of nested loops. However, using variable names on 
the NEXT statements causes your program to 
execute somewhat slower. 
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FOR and NEXT 
Statements 


Active loops should be exited by setting the loop 
counter out of range or setting a conditional 
statement with the loop causing the loop to ‘> 
terminate, so that every iteration of the FOR , 
statement in the loop has a corresponding NEXT. 


If a NEXT statement is encountered before its 
corresponding FOR statement, a FOR...NEXT error 
(FN) occurs. 


Examples: The first example shows a FOR...NEXT loop with a 
STEP value of 2. 


10 J=1@0: K=3@ 

“0 FOR fei TO:d STEP 2 
30 PRINT I; 

4Q K=K+1@ 

50 PRINT K 

60 NEXT 


Results: 


49 
50 
60 
79 
80 


es ees Nh © yh OBS 


In the following example, the loop does not execute 
because the initial value of the loop is more than the 
final value: 


10 J=@ 

20 FOR I=1 TO J 
30 PRINT I 

40 NEXT I 
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FOR and NEXT 
Statements 


The next program results in a FN error at compile 
time. There can be only one NEXT statement for 
every FOR statement. (This is different from other 
versions of BASIC that allow a different physical 
NEXT statement when jumping out of a loop.) 


19 FOR I=1 TO 5 
20 IF I=2 GOTO 50 
30 NEXT 

49 GOTO 60 

98 NEXT 

6% END 


In the following example, the loop executes 10 
times. The final value for the loop variable is always 
set before the initial value is set. (This is different 
from some other versions of BASIC, which set the 
initial value of the counter before setting the final 
value. In another BASIC, the loop in this example 
might execute six times.) 


19 1=5 
2Y FOR J=1 10. [35 


38 PRINT 1; 
40 NEXT 


Results: 


P23 4 See oe 
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FRE 
Function 


Purpose: Returns the amount of available memory. ‘> 


Versions: Cartridge Disk Advanced Compiler 
* KK * KK * KK * KOK 


Format: v = FRE(-1) 
v = FRE(x) 
vy = FRE(x3$) 
Remarks: «x and x$ are dummy arguments. 
FRE can return these different types of information: 


. FRE(-1) returns the amount of free space for 
dynamic numeric arrays. 


e FRE with any other numeric argument returns 
the size of the next free block of string space. 
Normally, this is also the largest block of string 
space. 


e FRE with any string value causes a 
housecleaning before returning the number of 
free bytes. During housecleaning, BASIC 
collects all of its useful data and frees up unused 
areas of memory once used for strings. The data 
is compressed so you can continue until you 
really run out of space. 


If a string allocation exceeds the size of the current 

block, the compiler either finds a free block large “a 
enough to hold the string, or it does a housecleaning. 

This function can be used as an indicator of when a 
housecleaning may take place. 
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Example: 


FRE 
Function 


You can improve the performance of programs that 
execute many string functions by using the MID$ 
statement to access substrings imbedded within one 
large string. This prevents fragmentation of string 
space. See ‘““MID$ Statement’’ for an example. 


Note: Ctrl-Break cannot be used during 
housecleaning. 


The actual value returned by FRE on your computer 
can differ from this example. 


PRINT FRE(Q) 
Results: 


14542 
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GET 


Statement (Files) 


Purpose: 


Versions: 


Format: 


Remarks: 


150 


Reads a record from a random file into a random 
buffer. 


Cartridge Disk Advanced Compiler 


KK KOK * 2 KK 


GET [#|filenum|[, number] 


filenum — is the number under which the file was 
opened. 


number — is the number of the record to be read, in 
the range 1 to 16775616. If number is 
omitted, the next record (after the last 
GET or PUT) is read into the buffer. 


After a GET statement, INPUT #, LINE INPUT #, 
or references to variables defined in the FIELD 
Statement can be used to read characters from the 
random file buffer. See ““BASIC Disk Input and 
Output” in the BASIC Compiler 2.00 Fundamentals 
for more information on using GET. 


Because DOS blocks as many records as possible in 
512-byte sectors, the GET statement does not 
necessarily perform a physical read from the disk. 


GET can also be used for communications files. In 
this case number is the number of bytes to read from 
the communications buffer. This number cannot 
exceed the value set by the LEN option on the 
OPEN “COM... statement. 


Example: 


GET 
Statement (Files) 


In DOS 2.1 and later versions, files can have up to 
16 megabytes. Random files in BASIC have fixed 
length records. The requested record number in a 
GET or PUT statement is multiplied by this fixed 
record length to form a 24-bit product. This value is 
then used to move the random file pointer by a DOS 
call to read or write the desired record. The 16 
megabyte value has some restrictions: 


e The total file size can be up to 16 megabytes, so 
the largest record number available is: 


16775616/record length 
« File size is limited by the available disk space. 


This example opens the file ““CUST”’ for random 
access, with fields defined in line 20. The GET 
statement on line 30 reads a record into the file 
buffer. Line 40 displays the information from the 
record that was read. 


1? OPEN: "A: CUST SRS #1 

20 FIELD 1, 3@ AS CUSTNAME$, 3@ AS ADDR$, 
30° AS ‘Cis 

SOc GE Tra 

40 PRINT CUSTNAME$, ADDR$, CITY$ 
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GET 


Statement (Graphics) 


Purpose: 


Versions: 


Format: 


Remarks: 
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Reads points from an area of the screen. 


Cartridge Disk Advanced Compiler 


* KK ** K KK 


Graphics mode only. 


GET (x1,y1)-(x2,y2),arrayname 


(x1,yl), (x2,y2) 
are coordinates in either absolute or 
relative form. Refer to “Specifying 
Coordinates” under ‘‘Graphics 
Modes”? in BASIC Compiler 2.00 
Fundamentals for more information on 
coordinates. 


arrayname is the name of the array you want to 
hold the information. 


GET reads the attributes of the points within the 
specified rectangle into the array. The specified 
rectangle has points (x/,y/) and (x2,y2) as opposite 
corners. (This is the same as the rectangle drawn by 
the LINE statement using the B option.) 


GET and PUT can be used for high-speed object 
motion in graphics mode. You might think of GET 


and PUT as ‘‘bit pump” operations that move bits 
onto (PUT) and off ( ET) the screen. Remember 


that PUT and GET are also used for random access 
files, but the syntax of these statements is different. 


GET 
Statement (Graphics) 


The array is used simply as a place to hold the image 
and must be numeric; it can be any precision, 
however. The required size of the array, in bytes, is: 


4+INT((x*bitsperpixel+7)/8)*y 


where x and y are the lengths of the horizontal and 
vertical sides of the rectangle, respectively. 


The following table contains the number of bits per 
pixel for each screen mode. 


Bits per Pixel 
SCREEN 1 LOG,(4) 
SCREEN 2 LOG,(2) 


For example, suppose you want to use the GET 
statement to get a 10 by 12 image in medium 
resolution. The number of bytes required is 
4+INT((10*2+7)/8)*12, or 40 bytes. The bytes 
per element of an array are: 


« 2 for integer string 
e 4 for single-precision string 
e § for double-precision string. 
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GET 
Statement (Graphics) 


Therefore, you could use a static integer array with 
at least 20 elements. Because dynamic arrays are 
allocated in 16-byte increments your array size must 
be a multiple of 16, otherwise an Illegal function call 
error occurs. 


The information from the screen is stored in the 
array as follows: 


1. 2 bytes giving the x dimension in bits 
2. 2 bytes giving the y dimension in bits 
3. The data itself. 


It is possible to examine the x and y dimensions and 
even the data itself if an integer array is used. The x 
dimension is in element O of the array, and the y 
dimension is in element 1. 


Keep in mind that integers are stored low byte first, 
then high byte, but the data is actually transferred 
high byte first, then low byte. 


The data for each row of points in the rectangle is 
left-justified on a byte boundary, so if less than a 
multiple of 8 bits is stored, the rest of the byte is 
filled with zeros. 
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GET 
Statement (Graphics) 


PUT and GET work significantly faster in medium 
resolution when x/ MOD 4 is equal to zero, and in 
high resolution when xJ MOD &8 is equal to zero. 
This is a special case where the rectangle boundaries 
fall on the byte boundaries. 


See ‘““SSCREEN Statement” for detailed information 
on the various screen modes. 


Example: See ‘““PUT Statement (Graphics)”’ for an example. 
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GOSUB and RETURN 
Statements 


Purpose: — Branches to and returns from a subroutine. 


Versions: Cartridge Disk Advanced Compiler 


Format: GOSUB [ine | label 


RETURN 
Remarks: 


line is the line number of the first line of the 
subroutine. 


label is asequence of 1 to 40 letters, digits, or 
periods, in any combination. 


The use of mnemonic labels makes your 
programs easier to read and maintain. Labels 
can be used as targets of most statements 
where line numbers are currently permitted, 
with the following exceptions: 


IF (condition) THEN (line number) 
and 


RUN (dine number) 
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GOSUB and RETURN 
Statements 


In each of these cases, only a line number is 
permitted in the statement. However, for 
both of these cases, the explicit use of a 
GOTO statement allows a label to be used. 
For example: 


IF A>10 THEN GOTO BAD.DATA 


To distinguish labels from keywords or 
variables, each label must be followed by a 
colon (:) when it starts a line. 


Note: If you wish to use error reporting 
(with the ERL variable) and error 
trapping, you must use line numbers. 


Numeric labels, alphanumeric labels, and line 
numbers can be intermixed in the same 
program, and numeric or alphanumeric labels 
may be used without the /N switch. 


A subroutine can be called any number of times in a 
program, and a subroutine can be called from within 
another subroutine. Such nesting of calls is limited 
only by available memory. 


The RETURN statement causes BASIC to branch 
back to the statement following the most recent 
GOSUB statement. A subroutine can contain more 
than one RETURN statement, so you can return 
from different points in the subroutine. Subroutines 
can appear anywhere in the program. 


To prevent your program from accidentally entering 
a subroutine, you can put a STOP, END, or GOTO 
statement before the subroutine to direct program 
control around it. 
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GOSUB and RETURN 
Statements 


Example: 
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Use ON...GOSUB to branch to different subroutines 
based on the result of an expression. 


See also ‘““CALL Statement.” ‘> 


This example shows how a subroutine works. The 
GOSUB in line 10 calls the subroutine in line 40. 
The program branches to line 40 and starts executing 
statements there until it sees the RETURN statement 
in line 70. At that point the program goes back to 
the statement after the subroutine call; that is, it 
returns to line 20. The END statement in line 30 
prevents the subroutine from being performed a 
second time. 


19 GOSUB 49 

20 PRINT “BACK FROM SUBROUTINE" 

3% END 

49 PRINT “SUBROUTINE”; 

50 PRINT ° IN'; ~ 
60 PRINT "“ PROGRESS" 

7Q@ RETURN 


Results: 


SUBROUTINE IN PROGRESS 
BACK FROM SUBROUTINE 


GOTO 
Statement 


Purpose: Branches unconditionally out of the normal program 
sequence to a specified line number or label. 


Versions: Cartridge Disk Advanced Compiler 


(**) (**) (**) kK 
Format: GOTO line | label 
Remarks: 

line is the line number of a line in the program. 


label is asequence of 1 to 40 letters, digits, or 
periods, in any combination. 


The use of mnemonic labels makes your 
programs easier to read and maintain. Labels 
can be used as objects of most statements 
where line numbers are currently permitted, 
with the following exceptions: 


IF (condition) THEN (line number) 
and 
RUN (line number) 


In each of these cases, only a line number is 
permitted in the statement. However, for 
both of these cases, the explicit use of a 
GOTO statement allows a label to be used. 
For example: 


IF A>10 THEN GOTO BAD.DATA 


GOTO 


Statement 
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To distinguish labels from keywords or 
variables, each label must be followed by a 
colon (:) when it starts a line. 


Note: If you wish to use error reporting 
(with the /E or /X option) and error 
trapping, you must use line numbers. 


Numeric labels, alphanumeric labels, and line 
numbers can be intermixed in the same 
program, and numeric or alphanumeric labels 
may be used without the /N switch. 


If /ine is the line number of an executable statement, 
that statement and those following are executed. If 
line refers to a nonexecutable statement (such as 
REM or DATA), the program continues at the first 
executable statement encountered after /ine. 


Use ON...GOTO to branch to different lines based 
on the result of an expression. 


Examples: 


GOTO 
Statement 


In this example, the GOTO statement in line 60 puts 
the program into an infinite loop, which is stopped 
when the program runs out of data in the DATA 
Statement. (Notice how branching to the DATA 
statement does not add additional values to the 
internal data table.) 


10 DATA 5,7,12 

20 READ R 

32: PRINT “R= "SRe 
40 A = 3.14*RA2 

50 PRINT "AREA = "3A 


68 GOTO 10 

Results: 

R= 5 AREA = 78.5 
R=/7 AREA = 153.86 
R= 12 AREA = 452.16 


Out of DATA in module mame at address nnnn:nnnn 
Hit any key to return to system 


The following example illustrates how labels can be 
used as targets instead of line numbers. 


PRINT "ENTER WHAT TYPE PET YOU HAVE" 
INPUT A$ 

IF A$="CAT" THEN GOTO FELINE 

IF A$="RAZORBACK" THEN GOTO GATOR 
PRINT “IT MUST BE A LADYBUG THEN" 


GOTO 961 

FELINE: PRINT ° OFS HOW TS HE?" 
GOTO 961 

GATOR: PRINT " ARE HIS TEETH SHARP ?" 
961<-END 
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HEXS$ 
Function 


Purpose: Returns a string that represents the hexadecimal 
value of the decimal argument. 


Versions: Cartridge Disk Advanced Compiler 
* KK ** KK KK 2K KK 


Format: v$ = HEX$(n) 
Remarks: 


n is a numeric expression in the range -32768 to 
65535. 


If n is negative, the twos complement form is used. 
That is, HEX$(-n) is the same as HEX$(65536-n). 


See ““OCTS Function” for octal conversion. ~ 


Example: The following example uses the HEX$ function to 
figure the hexadecimal representation for the two 
decimal values that are entered. 


1Q@ INPUT X 
20 A$ = HEX$(X) 
30 PRINT X " DECIMAL IS ";A$ "“ HEXADECIMAL” 


Results: 


(ieee Y2 
32 DECIMAL IS 2@ HEXADECIMAL 


? 1023 “ 
1023 DECIMAL IS 3FF HEXADECIMAL 
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YY Purpose: 


Versions: 


Format: 


Remarks: 


IF 
Statement 


Makes a decision regarding program flow based on 
the result of an expression. 


Cartridge Disk Advanced Compiler 


IF expression [,/THEN [clause] [,][ ELSE [clause]] 


IF expression [,)GOTO line | label [,|[ ELSE [clause]] 


expression can be any numeric expression. 


clause can be a BASIC statement or a 
sequence of statements (separated by 
colons); or it can be simply the 
number of a line to branch to. 


line is the line number of a line existing in 
the program. 


label is a sequence of 1 to 40 letters, digits, 
or periods, in any combination. 


The use of mnemonic labels makes 


your programs easier to read and 
maintain. 
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IF 
Statement 


Labels can be used as objects of most 
statements where line numbers are 


currently permitted, with the ‘> 
following exceptions: 


IF (condition) THEN (line 
number) 


and 
RUN line number) 


In each of these cases, only a line 
number is permitted in the statement. 
However, for both of these cases, the 
explicit use of a GOTO statement 
allows a label to be used. For 
example: 


IF A>10 THEN GOTO BAD.DATA ~ 


To distinguish labels from keywords 
or variables, each label must be 
followed by a colon (:) when it starts 
a line. 


Note: If you wish to use error 
reporting (with the ERL 
statement) and error trapping, 
you must use line numbers. 


Numeric labels, alphanumeric labels, 
and line numbers can be intermixed in 
the same program, and numeric or 
alphanumeric labels may be used 


without the /N switch. = 
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IF 
Statement 


If the expression is true (not zero), the THEN or 
GOTO clause is executed. THEN is followed by 
either a line number for branching or one or more 
statements to be executed. GOTO is always 
followed by a line number or a label. 


If the result of expression is false (zero), the THEN 

or GOTO clause is ignored, and the ELSE clause, if 
present, is executed. Execution then continues with 
the next executable statement. 


Note: When using IF to test equality for a value 
that is the result of a single-precision or 
double-precision computation, remember that 
the internal representation of the value may not 
be exact. (This is because single-precision and 
double-precision values are stored internally in 
floating-point binary format.) Therefore, the 
test should be against the range over which the 
accuracy of the value can vary. For example, to 
test a computed variable A against the value 1.0, 
use: 


IF ABS (A-1.pea seo THEN... 


This test returns a true result if the value of A 
is 1.0 with a relative error of less than 1.0E-6. 
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IF 
Statement 


Also note that IF... THEN...ELSE is just one 
statement. Once an IF statement occurs on a line, 
everything else on that line is part of the IF 
Statement. Because IF...THEN...ELSE is all one 
statement, the ELSE clause cannot be a separate 
program line. For example: 


19 IF A=B THEN X=4 
20 ELSE P=Q 


is invalid. Instead, it should be: 
19 IF A=B THEN X=4 ELSE P=Q 


Nesting of IF Statements: IF... THEN...ELSE 
statements can be nested. Nesting is limited only by 
the length of the line. For example: 


IF X>Y THEN PRINT "GREATER" ELSE IF Y>X 
THEN PRINT "LESS THAN" ELSE PRINT "EQUAL" ~ 


is a valid statement. If the statement does not 

contain the same number of ELSE and THEN 
clauses, each ELSE is matched with the closest 
unmatched THEN. For example: 


IF A=B THEN IF B=C THEN PRINT "“A=C" 
ELSE PRINT "A<>C" 


does not print ““A<>C” when A<>B. 
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Examples: 


IF 
Statement 
This statement gets record I if I is not zero: 


100 IF 1 THEN Gevegees 


In the next example, if I is between 10 and 20, DB 

is calculated and execution branches to line 300. If I 
is not in this range, the message Out of range is 
printed. Note the use of two statements in the 
THEN clause. 


100 IF (I>1@) AND (1<2@) THEN 
DB=1982-I: GOTO 300 
ELSE PRINT "OUT OF RANGE" 


In the next example, in line 20 everything after the 
THEN is part of the clause. This means that the 
NEXT is not executed unless N=I. When line 

20 executes, N does not equal I so the IF evaluation 
is false. Therefore, the NEXT is not performed and 
the program falls through to line 30. The NEXT 
must be coded on a separate line if you want the 
program to loop until N=I. 


1@ N=15 

20 FOR I=1 TO 2@:1F N=I THEN 4@0:NEXT 
30 PRINT "N <> I":END 

49 PRINT "N = I" 


Results: 


, ae | 
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IF 
Statement 


The following program loops, asking “DONE?”, 
until the user types “Y”. Notice that both PRINT 
“YES” and DONE=-1 are part of the IF clause. 


DONE=0 
WHILE NOT DONE 
PRINT "DONE?" ; 
A$=INPUT$(1) 
IF Ag="y" OR Ag="y" 
THEN PRINT "YES" :DONE=-1 
ELSE PRINT "NO" 
WEND 


Suppose you enter “‘Y”’. 


Results: 


YES 
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YU Purpose: 


Versions: 


Format: 


Remarks: 


INKEYS$ 
Variable 


Reads a character from the keyboard. 


Cartridge Disk Advanced Compiler 


* KK KOK * kK * KOK 


INKEY$ reads only a single character, even if 
several characters are waiting in the keyboard buffer. 
The returned value is a O-, 1-, or 2-character string. 


« A null string (length zero) indicates that no 
character is pending at the keyboard. 


e A 1-character string contains the actual 
character read from the keyboard. 


e A 2-character string indicates a special extended 
code. The first character is hex 00. For a 
complete list of these codes, see ““ASCII 
Character Codes.”’ 


You must assign the result of INKEY$ to a string 
variable before using the character with any BASIC 
Statement or function. 


While INKEY$ is being used, no characters are 
displayed on the screen and all characters are passed 
through to the program except for: 


e Ctrl-Break, which stops the program 

° Ctrl-Num Lock, which sends the system into a 
pause state 

e Alt-Ctrl-Del, which does a System Reset 

* Shift-PrtSc, which prints the screen. 
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INKEYS$ 
Variable 


Examples: 


If you press Enter in response to INKEY$, the 
carriage return character passes through to the 
program. 


The following section of a program stops execution 
until any key is pressed: 


100 PRINT "Press any key to continue" 
110 A$=INKEY$: IF A$="" THEN 119 


The next example shows program lines that can be 
used to test a two-character code being returned: 


109 KBS=INKEY$ 
110 IF LEN(KB$)=2 THEN KB$=RIGHT$(KB$,1) 


ry 


YU Purpose: 


Versions: 


Format: 


Remarks: 


Example: 


INP 
Function 


Returns the byte read from port n. 


Cartridge Disk Advanced Compiler 


26 OK OK OK * KK * OK 


v = INP(n) 
n must be in the range O to 32767. 


INP is the complementary function to the OUT 
statement. See “OUT Statement.”’ 


INP performs the same function as the IN instruction 
in assembly language. See also the IBM Personal 
Computer Technical Reference for a description of 
valid port numbers (I/O addresses). 


This example turns the speaker on, waits for a 
keypress, then turns the speaker off. 


10@ A=INP(&H61) 

11Q@ OUT &H61, A OR 3 : REM Speaker on 

12@ WHILE INKEY$="" : WEND 

13@ OUT &H61, A AND NOT 3 : REM Speaker off 
14Q END 
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INPUT 
Statement 


Purpose: Receives input from the keyboard during program 
execution. 


Versions: Cartridge Disk Advanced Compiler 
* KK * 2k 2k * KK 


Format: INPUT]; ][ ‘“prompt’’; | ,] variable[,variable)... 
Remarks: 


“prompt’’ is a String constant that prompts for the 
desired input. 


variable is the name of the numeric or string 
variable or array element that receives 


the input. ~ 


When the program sees an INPUT statement, it 
pauses and displays a question mark on the screen to 
indicate that it is waiting for data. If a “‘promp?’’ is 
included, the string is displayed. If ‘“‘prompt’’ is 
followed by the semicolon (;), a question mark 
follows the displayed string; if ““promp?’’ is followed 
by a comma, the question mark is not displayed. For 
example, the statement: 


INPUT "ENTER BIRTHDATE" ,B$ 


prints the prompt without the question mark. 
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INPUT 
Statement 


After the prompt or question mark is displayed, you 
can enter the required data from the keyboard. The 
input editor supplied with BASIC Compiler 2.00 
allows you to easily alter the response to an input 
Statement if a mistake is made. Any corrections 
must be made before the Enter key is pressed. See 
BASIC Compiler 2.00 Fundamentals for more 
information on the input editor. 


The data you enter is assigned to the variables given 
in the variable list. The data items you supply must 
be separated by commas, and the number of data 
items must be the same as the number of variables in 
the list. 


The type of data item that you enter must agree with 
the type specified by the variable name. (Strings 
entered in response to an INPUT statement need not 
be surrounded by quotation marks.) 


If you respond to INPUT with too many or too few 
items, or with the wrong type of value (letters 
instead of numbers, etc.), BASIC displays the 
message ?Redo from start. If a single variable is 
requested, you can simply press Enter to indicate the 
default values of 0 for numeric input or null for 
String input. However, if more than one variable is 
requested, pressing Enter causes the ?Redo from start 
message to be printed because too few items were 
entered. BASIC does not assign any of the input 
values to variables until you give an acceptable 
response. 


If INPUT is immediately followed by a semicolon, 
pressing Enter to input data does not produce a 
carriage return/line feed sequence on the screen. 
This means that the cursor remains on the same line 
as your response. 
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INPUT 
Statement 
Examples: In this example, the question mark displayed by the 


computer is a prompt to tell you it wants you to enter 
something. 


19 INPUT X 
20 PRINT X "SQUARED IS" XA2 
39 END 


Results: 


? 


Suppose you enter a 5. 


The program continues: 


7 a 
5 SQUARED IS 25 


For this second example, a prompt was included in 
line 20, so this time the computer prompts with 
“WHAT IS THE RADIUS?” 


19 PI=3.14 

20 INPUT "WHAT IS THE RADIUS";R 

30 A=PI*RAZ2 

49 PRINT "THE AREA OF THE CIRCLE IS ";A 
of END 


Results: 


WHAT IS THE RADIUS? 
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INPUT 
Statement 


Suppose you respond with 7.4. The program 
continues: 


WHAT IS THE RADIUS? 7.4 
THE AREA OF THE CIRCLE IS 171.9464 
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INPUT# 
Statement 


Purpose: 


Versions: 


Format: 


Remarks: 
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Reads data items from a sequential device or file and ‘> 
assigns them to program variables. 


Cartridge Disk Advanced Compiler 


* KK * OK * * 


INPUT #filenum, variable |,variable]... 


filenum is the number used when the file was 
opened for input. 


variable is the name of a variable that will have 
an item in the file assigned to it. It can 
be a string or numeric variable or an 
array element. ~ 


The sequential file can reside on disk. It can be a 
sequential data stream from a communications 
adapter, or it can be the keyboard (KYBD:). 


The type of data in the file must match the type 
specified by the variable name. Unlike INPUT, no 
question mark is displayed with INPUT #. 


The data items in the file must appear just as they 

would if the data were being typed in response to an 

INPUT statement. With numeric values, the leading 

spaces, carriage returns, and line feeds are ignored. 

The first character encountered that is not a space, 

carriage return, or line feed is assumed to be the start 

of the number. The number ends with a space, “ 
carriage return, line feed, or comma. 


Example: 


INPUT# 
Statement 


If BASIC is scanning the data for a string item, the 
leading spaces, carriage returns, and line feeds are 
also ignored. The first character encountered that is 
not a space, carriage return, or line feed is assumed 
to be the start of the string item. If this first 
character is a quotation mark (‘‘), the string item 
consists of all characters read between the first 
quotation mark and the second. Thus, a quoted 
string cannot contain a quotation mark as a 
character. If the first character of the string is not a 
quotation mark, the string is an unquoted string. It 
ends after a comma, carriage return, or line feed, or 
after 255 characters have been read. If end of file is 
reached when a numeric or string item is being input, 
the item is canceled. 


See “‘BASIC Disk Input and Output,” in BASIC 
Compiler 2.00 Fundamentals. 
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INPUTS 
Function 


Purpose: Returns a string of n characters read from the 
keyboard or from file number /filenum. 


Versions: Cartridge Disk Advanced Compiler 
* KK * KK ** KK * OK 


Format: v$ = INPUTS$(n[,[#|filenum]) 
Remarks: 


n is the number of characters to be read 
from the file. 


filenum _ is the file number used on the OPEN 
statement. If filenum is omitted, the 
keyboard is read. 


If the keyboard is used for input, no characters are ® 
displayed on the screen. All characters (including 

control characters) are passed through except 

Ctrl-Break, which is used to interrupt the execution 

of the INPUT$ function. When responding to 

INPUTS from the keyboard, it is not necessary to 

press Enter. 


The INPUTS function allows you to read ASCII 
characters that normally are assigned special control 
functions, such as Backspace (ASCII code 8). If you 
want to read these special characters, you should use 
INPUTS or INKEY$ (not INPUT or LINE INPUT). 
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Examples: 


INPUTS 
Function 


For communications files, the INPUT$ function is 
preferred over the INPUT # and LINE INPUT # 
statements, since all ASCII characters can be 
significant in communications. See also 
“Communications” in BASIC Compiler 2.00 
Fundamentals. 


The following program lists the contents of a 
sequential file in hexadecimal. 


10 OPEN "DATA" FOR INPUT AS #1 

20 IF EOF(1) THEN 5@ 

3Q@ PRINT HEX$(ASC(INPUT$(1,#1))); 
40 GOTO 20 

58 PRINT 

60 END 


The next example reads a single character from the 
keyboard in response to a question. 


100 PRINT "TYPE P TO PROCEED OR S TO STOP" 
11@ X$=INPUT$(1) 

120 IF X$="P" THEN 50@ 

130 IF X$="S" THEN 700 ELSE 100 
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INSTR 


Function 


Purpose: 


Versions: 


Format: 


Remarks: 
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Searches for the first occurrence of string y$ in x$ 
and returns the position at which the match is found. 
The optional offset m sets the position for starting the 
search in x$. 


Cartridge Disk Advanced Compiler 


* KO KK * KOK fk 


v = INSTR([n,]x$,y$) 


n is a numeric expression in the range | to 
S2rQ}. 


x$, y$ can be string variables, string expressions, 
or string constants. ~ 


If n>LEN(xS), or if x$ is null, or if y$ cannot be 
found, INSTR returns 0. If y$ is null, INSTR returns 
n (or 1 if n is not specified). 


If n is out of range, an Illegal function call error is 
returned. 


Example: 


INSTR 
Function 


This example searches for the string ““B”’ within the 
string ‘““ABCDEB”’. When the string is searched from 
the beginning, “‘B”’ is found at position 2; when the 
search starts at position 4, “‘B”’ is found at position 6. 


10 A$ = "ABCDEB" 
20 BS inte ad «Ea 
3@ PRINT INSTR(A$,B$);INSTR(4,A$,B$) 


Results: 


6-6 
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INT 


Function 


Purpose: 


Versions: 


Format: 


Remarks: 


Example: 
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Returns the largest integer that is less than or equal 
to x. 


Cartridge Disk Advanced Compiler 


* K * K * KK * KK 
v = INT(x) 
x is any numeric expression. 


This is called the ‘‘floor’’ function in some other 
programming languages. 


See also “FIX” and ““CINT”’ functions. (They also 
return integer values. ) 


This example shows how INT truncates positive 
integers but rounds negative numbers upward (in a 
negative direction). 

PRINT INT(45.67) 


Results: 


45 


PRINT INT(-2.89) 
Results: 


= 


oe Purpose: 


Versions: 


Format: 


Remarks: 


IOCTL 
Statement 


Allows BASIC to send a control data string to a 
device driver anytime after the driver has been 
opened using OPEN. 


Cartridge Disk Advanced Compiler 


* KOK ** KOK * KO 


IOCTL [#|filenum, string 


filenum _ is the file number of the device driver. 


string is a string expression containing the 
control data. 


BASIC’s file I/O system allows you to create and 
install your own device drivers. The IOCTL 
statement and the IOCTL$ function send control 
data to and read data from your device driver. 


An IOCTL command string can be up to 32767 
bytes long. Multiple commands within the string can 
be separated by semicolons: 


"LF;PL66;LW132" 
You define the content and format of the control 


data string. The possible commands are determined 
by the characteristics of the driver installed. 
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IOCTL 
Statement 


Example: Initially, character device drivers for LPT1:, LPT2:, 
and LPT3: are installed, but they can be replaced. If 
you install a driver called LPT1 (no colon) to replace 
LPT 1: and that driver is able to set page length, an 
IOCTL command string to set or change the page 
length might be: 


"PLn" (where n is the new page length) 


You can then open the new LPT1 driver and set the 
page length with: 


OPEN "LPT1" FOR OUTPUT AS #1 
IGCTi 4a FL 60" 


You could, for instance, write a device driver that 
controls a monitor and is capable of setting the mode 
of the screen to color and also capable of setting the 
width of the screen. For example: 


OPEN "OPT" FOR OUTPUT AS #2 
IOCTL #2, "CL: W4Q" 


Assuming that your new driver accepts a command 
called ‘‘CL”’ to change the screen to color and a 
command called ‘‘Wn’’ to set the width of the screen, 
the previous example passes those commands to your 
driver and causes the screen to respond. 


Note: For related information, see “IOCTL$ 
Function” in this manual, ‘“‘Device Drivers”’ in 
the BASIC Compiler 2.00 Fundamentals, and 
the device driver section of Disk Operating 
System Technical Reference. 
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w Purpose: 


Versions: 


Format: 


Remarks: 


Example: 


IOCTLS 


Function 


Reads a control data string from a device driver that 
is open. 


Cartridge Disk Advanced Compiler 


KK * KK * 


v$ = IOCTL$([#|filenum) 


filenum is the number of the file open to the 
device. 


The IOTCL$ function can be used to get 
acknowledgment that an IOCTL command has 
succeeded or failed. It can also be used to get device 
configuration information, such as device width. 


This example checks to see if control data was 
successfully received. 


19 OPEN "COMM" AS #1 
20 IOCTL #1, "SW132;GW" 
30° IF LOCTUS(T aaes ae. 
THEN PRINT “WIDTH SET SUCCESSFULLY" 


If the device driver ‘““COMM”’ returns a value not 
equal to 132 from the IOCTL$ request, your 
command was not processed successfully, and you 
should check for errors. If a device failure occurs, 
check the system variables of ERDEV and 
ERDEVS$S. 
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KEY 
Statement 


Purpose: _ Sets or displays the soft keys. 


Versions: Cartridge Disk Advanced Compiler 


Format: KEY ON 
RE Y:OFF 
KEY -LIST 
KEY n, x$ 
KEY n, CHR$(KBflag) + CHR$(scan code) 
Remarks: All function keys are initially set to null values. In =) 
order to display the function key values with the 


KEY ON statement, values must first be assigned 
with KEY nv, x$. 


KEY ON causes the function Key values to be 
displayed on the 25th line. 


When the width is 40, 5 of the 10 function keys are 
displayed. When the width is 80, all 10 are 
displayed. In either width, only the first 6 characters 
of each value are displayed. 


KEY OFF erases the function key display from the a” 
25th line, making that line available for program use. 
It does not disable the function Keys. 
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KEY 
Statement 


After turning off the function key display with KEY 
OFF, you can use LOCATE 25,1 followed by 
PRINT to display anything you want on the bottom 
line of the screen. Information on line 25 is not 
scrolled, as are lines 1 through 24. 


KEY LIST lists all 10 function key values on the 
screen. All 15 characters of each value are 
displayed. 


KEY n,x$ allows you to set each function key to 
automatically type any sequence of characters. OFF 
is the default state for the function Key display. 


n is the function key number in the range 1 to 
10. 
x$ is a String expression that is assigned to the 


key. (Remember to enclose string constants in 
quotation marks.) 


The value of a function key n is reassigned the value 
of the string x$. If the value entered for n is not in 
the range 1 to 10, an Illegal function call error occurs. 
The previous key string assignment is retained. x$ 
can be O to 15 characters long. If it is longer than 15 
characters, only the first 15 characters are assigned. 


Assigning a null string to a function Key disables the 
function key. 


If a function key is defined, the INKEY$ function 
returns one character of the function key string each 
time it is called. If a function key is not defined, the 
first character is binary zero, the second is the key 
scan code, as listed under “ASCII Character Codes.”’ 


There are also six definable key traps. With this 
capability, you can trap any key you define. 
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KEY 
Statement 


These additional keys are defined by the statement: 


KEY n,CHR$(KBflag)+CHR$(scan code) ‘> 
n is a numeric expression in the range 15 
to 20. 


KBflag is a mask for the latched keys. The 
appropriate bit in KBflag must be set in 
order to trap a key that is shifted, 
Alt-shifted, or Ctrl-shifted. The KB/flag 
values in hex are: 
Caps Lock &HO—Caps Lock is not active. 
Caps Lock &H40—Caps Lock is active. 
Num Lock &HO—Num Lock is not active. ~ 
Num Lock &H20—Num Lock is active. 
Alt &HO8—ALT key is pressed. 
Ctrl &H04—Control key is pressed. 
Left Shift &HO2—Left Shift key is pressed. 
Right Shift &HO1-—Right Shift key is pressed. 
Scan code is the number identifying one of the 83 
keys to trap. See Appendix C, “‘Scan 
Codes” in BASIC Compiler 2.00 
Fundamentals. 
Note that key trapping assumes that the left and right “ 
Shift keys are the same, so you can use a value of 


&HO1, &HO2, or &HO3 (the sum of hex 01 and hex 
Q2) to denote a Shift key. 
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KEY 
Statement 


You can also add multiple shift states. For example, 
the Ctrl and Alt keys can be added together. Shift 
State values must be in hex. 


When trapping a key or key combinations, you must 
know the state of Num Lock and Caps Lock. 


When you trap keys, they are processed in the 
following order: 


1. Ctrl-PrtSc, which activates the line printer, is 
processed first. Even if Ctrl-PrtSc is defined as 
a trappable key, this does not prevent characters 
from being echoed to the line printer. 


2. Next, the function keys F1 to F10, Cursor Up, 
Cursor Down, Cursor Right, and Cursor Left 
(1-14) are processed. Setting scan codes 59 to 
68, 72, 75, 77, or 80 as Key traps has no effect, 
because they are considered to be predefined. 


3. Last, the keys you detime for 15 to 20 are 
processed. 


Notes: 


e Trapped keys do not go into the BIOS buffer so 
that only BASIC knows that the keys were 
pressed. 


e Be careful when you trap Ctrl-Break and 
Ctrl-Alt-Del; unless you have a test in your trap 
routine, you will have to turn the power off to 
stop your program. 


The following section, ““KEY(n) Statement,” 
explains how to enable and disable function key 


trapping. 
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KEY 


Statement 


Examples: This example displays the function keys on the 25th 
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line. 
50 KEY ON 


This example erases function key display. The 
function keys are still active, but not displayed. 


1Q KEY OFF 


This example assigns the string ‘““FILES’’+Enter to 
function key 1. 


10 KEY 3b EITEES -+CHRS$(13) 
This example disables function key 1. 


LO KEP Vises 


This example sets up a Key trap for capital P. Note 
that all three KEY statements—KEY, KEY(n), and 
ON KEY—are used with key trapping. 


10 KEY 15, CHR$(&H4@)+CHR$(25) 
20 ON KEY(15) GOSUB 19000 
30 KEY(15) ON 


This example sets up a Key trap for Ctrl-Shift A. 
Notice that the hex values for Ctrl (&H04) and Shift 
(&HO3) are added together to get the shift state. 


19 KEY 20, CHR$(&H@4+&HO3 )+CHR$ (30) 
20 ON KEY(2@) GOSUB 2000 
3 KEY(2@) ON 


Note: When specifying scan codes, you can use 
either hexadecimal or decimal notation. 


YY Purpose: 


Versions: 


Format: 


Remarks: 


KEY(n) 
Statement 


Activates and deactivates trapping of the specified 
key in a BASIC program. See ““ON KEY(n) 
Statement.” 
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KEY(n) ON 
KEY(n) OFF 


KEY(n) STOP 


n is a numeric expression in the range 1 to 20, 
and indicates the trapped key: 


1-10 function keys Fl to F10 


11 Cursor Up 

12 Cursor Left 
13 Cursor Right 
14 Cursor Down 


15-20 keys defined by the form: 
KEY n,CHR$(KBflag)+CHRS$(scan 
code). 


KEY(n) ON must be executed to activate trapping of 
function key or cursor control key activity. After 
KEY(n) ON, if a nonzero line number is specified in 
the ON KEY(n) statement, then every time the 
compiler starts a new statement or line, (depending 
on whether you compiled using /V, or /W), it checks 
to see if the specified key was pressed. 
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KEY(n) 


Statement 
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If so, it performs a GOSUB to the line number or 
label specified in the ON KEY(n) statement. A 

KEY(n) statement cannot precede an ON KEY(n) ‘> 
statement. 


If KEY(n) is OFF, no trapping takes place and, even 
if the key is pressed, the event is not remembered. 


Once a KEY(n) STOP statement has been executed, 
no trapping takes place. However, if you press the 
specified key, your action is remembered, so that an 
immediate trap takes place when KEY(n) ON is 
executed. 


KEY(n) ON has no effect on whether the function 
key values are displayed at the bottom of the screen. 


& Purpose: 


Versions: 


Format: 


Remarks: 


KILL 
Command 


Deletes a file from a disk. The KILL command in 
BASIC is similar to the ERASE command in DOS. 


Cartridge Disk Advanced Compiler 
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KILL filespec 


filespec is a String expression for the file 
specification. It can contain a path and 
must conform to the rules outlined 
under ‘“‘Naming Files” in BASIC 
Compiler 2.00 Fundamentals, 
otherwise, a Bad file name error occurs. 


KILL can be used for all types of disk files. The 
name must include the extension, if one exists. 


If a KILL statement is given for a file that is 
currently open, a File already open error occurs. 
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KILL 


Command 


Examples: To delete the file named ‘“‘DATA1” on drive A, you 
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might use: a“ 
200 KILL "A:DATA1" 


To delete the file “PROG.BAS” in the LEVEL2 
subdirectory, you might use: 


KILL "LEVEL1\LEVEL2\PROG.BAS" 


Note that KILL can be used only to delete files. 
The RMDIR command must be used to remove 
directories. 


& Purpose: 


Versions: 


Format: 


Remarks: 


LBOUND 
Function 


Returns the lower boundary (smallest available 
subscript) for a particular array. 
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v=LBOUND (array|,dim|) 


array is the name of the array. 


dim iS an integer constant that indicates the 
number of the dimension whose lower 
bound you are requesting. The default 
value is 1. 


LBOUND returns a value of 0 or 1 depending on the 
setting of the OPTION BASE statement. The 
default lower bound is 0. LBOUND and UBOUND 
are particularly useful for determining the size of an 
array passed to a subprogram. 


Note: See also ‘‘UBOUND Function.”’ 
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LBOUND 
Function 


Example: The following example uses LROUND and 
UBOUND to determine the size of the array to be 
sorted. ‘> 


200 OPTION BASE 1 

219 DIM SHARED A(1@) 

220 CLS 

230 PRINT "THE UNSORTED ARRAY" 

240 FOR I = LBOUND(A) TO UBOUND(A) 
250 READ A(1I) 

260 PRINT A(I) 

270 NEXT I 

280 CALL SORT 

290 PRINT "THE SORTED ARRAY" 

308 FOR I = LBOUND(A) TO UBOUND(A) 
310 PRINT A(1I) 

320 NEXT I 

339 DATA 40, 199, 19, 8, 66, 23 
340 DATA 83, 6, 54, 120, 25, 98 


359 END 

360 REM **** EXCHANGE SORT SUBPROGRAM **** “a 
370. SUB: SGer STATIC 

380 STATIC B 

399 REM USE LBOUND TO DETERMINE LOWER 

400 REM BOUNDARY OF ARRAY 

419 FOR I = LBOUND(A) TO UBOUND(A) - 1 


430 IF A(I) <= A(J) THEN 470 
449 B = A(J) 

450 A(J) = A(T) 

460 A(I) = 8B 

470 NEXT J 

480 NEXT I 

490 END SUB 
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LBOUND 
Function 


Results: 


YU THE UNSORTED ARRAY 


120 
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LEFTS 


Function 
Purpose: Returns the leftmost n characters of x$. ty 
Versions: Cartridge Disk Advanced Compiler 


Format: 


Remarks: 


Example: 
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v$ = LEFT$(x$,n) 


x$ is any string expression. 


n is a Numeric expression that must be in the 
range 0 to 32,767. It specifies the number of 
characters that are to be in the result. 


If n is greater than LEN(x3$), the entire string (x$) is 
returned. If n=O, the null string (length zero) is 
returned. 


See also ‘““MID$” and “RIGHT$”’ functions. 


In this example, the LEFT$ function is used to 
extract the first five characters from the string 
“BASIC PROGRAM.” 


18 A$ = "BASIC PROGRAM" 
20 BS = LEFT$(A$,5) 

30 PRINT B$ 

Results: 

BASIC 


we Purpose: 


Versions: 


Format: 


Remarks: 


Example: 


LEN 
Function 


Returns the number of characters in x8. 
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v = LEN(x3) 
x§$ is any string expression. 


Unprintable characters and blanks are included in 
the count of the number of characters. 


There are 14 characters in the string 
‘“‘BOCA RATON, FL”’ because the comma and the 
two blanks are counted. 


10 X$ = "BOCA RATON, FL" 
20 PRINT LEN(X$) 


Results: 


14 


199 


LET 
Statement 


Purpose: Assigns the value of an expression to a variable. “Ns 


Versions: Cartridge Disk Advanced Compiler 
* KK * KOK ** OK * ok 


Format: [LET] variable=expression 


Remarks: 


variable is the name of the variable or array 
element that is to receive a value. It 
can be a string or numeric variable or 
array element. 


expression is the expression whose value is 
assigned to variable. The type of the “ 
expression (string or numeric) must 
match the type of the variable, or a 
Type mismatch error occurs. 


The word LET is optional; that is, the equal sign is 
enough when assigning an expression to a variable 
name. 
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Examples: 


LET 
Statement 


This example assigns the value 40 to the variable 
HOURS. It then assigns the value 134, which is the 
value of the expression HOURS * 3.35 to the 
variable PAY. The string ''JOHN''is assigned to the 
variable EMPLOYEES. 


1@ LET HOURS=40 

20 LET PAY=HOURS*3.35 

3Q@ LET EMPLOYEE$=JOHN 

The same statements could have also been written: 
1@ HOURS=40 


20 PAY=HOURS*3.35 
3@ EMPLOYEE$=JOHN 
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LINE 
Statement 


Purpose: Draws a line or a box on the screen. ‘> 


Versions: Cartridge Disk Advanced Compiler 


Graphics mode only. 
Format: LINE [(xJ,y1)] -(x2,y2) [,[attribute] [,[B[F]]] Lstyvle]] 
Remarks: 


(xl), X22) 
are coordinates in either absolute or 
relative form. See “Specifying 
Coordinates” under ‘“‘Graphics Modes’ 
in BASIC Compiler 2.00 Fundamentals. ~ 


bd 


attribute is an integer expression that specifies a 
color attribute. In SCREEN 1, 
(medium resolution), attribute can range 
from 0 to 3. In SCREEN 2, (high 
resolution), attribute can be O or 1. 


The default color attribute for the 
foreground is the maximum color 
attribute for that screen mode. 


The default color attribute for the 
background is always zero. 
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LINE 
Statement 


style is a 16-bit integer mask used to put 
points on the screen. The style option is 
used for normal lines and boxes but 
cannot be used with filled boxes (BF). 
Using style with BF results in a Syntax 
error. This technique is called line 
styling. 
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LINE 


Statement 
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The simplest form of LINE is: 


LINE: =(X2,Y2) 


This draws a line from the last point referenced to 
the point (x2,y2) in the foreground attribute. 


We can include a starting point also: 
LINE (@,@)-(319,199) ‘diagonal down screen 


LINE (@,100)-(319,100) ‘horizontal bar 
across screen 


We can indicate the attribute in which to draw the 
line: 


LINE (10,10)-(20,20),2 ‘draw in attribute 2 


10 ‘draw random lines in random colors 
20 SCREEN 1,0,0,@: CLS 

3@ LINE -(RND*319,RND*199) ,RND*4 

40 GOTO 20 


10 ‘alternating pattern - line on, line off 
2@ SCREEN 1,0,0,@: CLS 

38 FOR X=@ TO 319 

4Q LINE (X,@)-(X,199),X AND 1 

50 NEXT 


The next argument to LINE is B (box), or BF (filled 
box). We can leave out color and include the 
argument: 


LINE (@,0)-(100,100),,B ‘box in foreground 
Or we can include the attribute: “» 


LINE (0,0)-(100,100) ,2,BF 
' filled box attribute 2 


LINE 
Statement 


The B tells BASIC to draw a rectangle with the 
points (x/,y/) and (x2,y2) as opposite corners. This 
avoids having to give the four LINE commands: 


EINE UAL YI) =(X2578o 
Ee Cha g¥ 4) (X1,Y2) 
Pret ae. ¥1) = (Xe ee 
Bite Ae 2) -(X2y hee 


that perform the equivalent function. 


The BF means “‘draw the same rectangle as B, but 
also fill in the interior points with the selected 
color.” 


The last argument to LINE is style. LINE uses the 
current circulating bit in style to plot (or store) points 
on the screen. If the bit is zero, no point is plotted. 
If the bit is one, a point is plotted. After each point, 
the next bit position in style is selected. When the 
last bit position has been selected, LINE ‘“‘wraps 
around” and begins with the first bit again. 


Note that a zero bit indicates ‘“‘no store’”’ and does 
not erase the existing point on the screen. You may 
want to draw a background line before a styled line 
to force a known background. 


The style option can be used to draw a dotted line 
across the screen by plotting (storing) every other 


point. Because style is 16 bits wide, the pattern for a 
dotted line looks like this: 


1@ IO 10 lee ee 1 0 


This is equal to XHAAAA in hexadecimal notation. 


LINE 


Statement 


Examples: To draw a dotted line: 
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1Q@ SCREEN 1,@ “ 
20 LINE (0,0)-(319,199),,,&HAAAA 


To draw a cyan box with dashes: 


19 SCREEN 1,9 
20 LINE (@,0)-(100,100) ,1,B,&HCCCC 


The last point referenced after a LINE statement is 
point (x2,y2). If you use the relative form for the 
second coordinate, it is relative to the first 
coordinate. For example, 


LINE (100,100)-STEP (10,-2@) 
draws a line from (100,100) to (110,80). 


This example draws random boxes filled with random 
colors. 


10 CLS , 

20 SCREEN 1,@: COLOR @,@ 

30 LINE -(RND*319,RND*199) ,RND*2+1 ,BF 
40 GOTO 30 ‘boxes will overlap 


LINE INPUT 
Statement 


YY Purpose: 


Versions: 


Format: 


Remarks: 


Reads an entire line (up to 32767 characters) from 
the keyboard into a string variable, ignoring 
delimiters. 
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LINE INPUT|[;]| ‘prompt’’;| stringvar 


‘prompt’? is a String constant that is displayed on 
the screen before input is accepted. A 
question mark is not printed unless it is 
part of the prompt string. 


stringvar is the name of the string variable or 
array element to which the line is 
assigned. All input from the end of the 
prompt to the Enter is assigned to 
stringvar. Trailing blanks are ignored. 


If LINE INPUT is immediately followed by a 
semicolon, pressing Enter to end the input line does 
not produce a carriage return/line feed sequence on 
the screen. That is, the cursor remains on the same 
line as your response. 
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LINE INPUT 
Statement 


Example: 
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The input editor supplied with BASIC Compiler 2.00 
allows you to easily alter your response, if you have 
made a mistake. You must make any corrections 
before the Enter key is pressed. 


See BASIC Compiler 2.00 Fundamentals for more 
information on the input editor. 


See the example in the next entry, ““LINE INPUT # 
Statement.” 


YU Purpose: 


Versions: 


Format: 


Remarks: 


LINE INPUT # 
Statement 


Reads an entire line (up to 32767 characters), 
ignoring delimiters, from a sequential file into a 
String variable. 
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LINE INPUT #filenum, stringvar 


filenum is the number under which the file was 
opened. 
stringvar is the name of a string variable or array 


element to which the line is assigned. 


LINE INPUT # reads all characters in the sequential 
file up to a carriage return. It then skips over the 
carriage return/line feed sequence, and the next 
LINE INPUT # reads all characters up to the next 
carriage return. (If a line feed/carriage return 
sequence is encountered, it is preserved. That is, the 
line feed/carriage return characters are returned as 
part of the string.) 


LINE INPUT # is especially useful if each line of a 
file has been broken into fields, or if a BASIC 
program saved in ASCII mode is being read as data 
by another program. 


See also ‘“‘BASIC Disk Input and Output,” in BASIC 
Compiler 2.00 Fundamentals. 
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LINE INPUT # 
Statement 


Example: The following example uses LINE INPUT to get 
information from the keyboard, where the 
information is likely to have commas or other ‘> 
delimiters. The information is then written to a 
sequential file, and read back out from the file using 
LINE INPUT #. 


10 OFEN = Gst...FOR OUTPUT. AS-¥1 
20 LINE INPUT “Address? "3;C$ 
oY PRINT #1, C$ 

40 CLOSE 1 

50 OPEN "LST" FOR INPUT AS #1 
OY Lame tert fl, C$ 

7Q@ PRINT C$ 

80 CLOSE 1 


Results: 


Address? 


Suppose you respond with DELRAY BEACH, FL 
33445. The program continues: 


Address? DELRAY BEACH, FL 33445 


DELRAY BEACH, FL 33445 


© Purpose: 


Versions: 


Format: 


Remarks: 


LOC 
Function 


Returns the current position in the file. 
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v = LOC(C/ilenum) 


filenum _ is the file number used when the file was 
opened. 


With random files, LOC returns the record number 
of the last record read or written to a random file 
since the file was opened. 


With sequential files, LOC returns the number of 
records read from or written to the file since it was 
opened. (A record for sequential files is a 128-byte 
block of data.) When a file is opened for sequential 
input, BASIC reads the first sector of the file, so 
LOC returns a 1 even before any input from the file. 


For a communications file, LOC returns the number 
of characters in the input buffer waiting to be read. 
The default size for the input buffer is 256 
characters, but this can be changed by using the /C: 
option at compile time. 
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LOC 
Function 


Examples: This example stops the program when the 50th 
record in the file is passed. 


108 IF LOC(1)>5@ THEN STOP ‘> 


This example could be used to rewrite the record 
that was just read. 


109 PUT #1,LO0C(1) 
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UU Purpose: 


Versions: 


Format: 


Remarks: 


LOCATE 
Statement 


Positions the cursor on the active screen. Optional 
parameters turn the blinking cursor on and off and 
define the size of the blinking cursor. 
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LOCATE [row]|,[co/][,[ cursor] ,[ start]|,stop|]]] 


row is a numeric expression in the range | to 
25. It indicates the screen line number 
where you want to place the cursor. 


col is a numeric expression in the range 1 to 
40 or | to 80, depending upon screen 
width. It indicates the screen column 
number where you want to place the 


Cursor. 


cursor is a value indicating whether the cursor is 
visible or not. A zero indicates off, one 
indicates on. 


start is the cursor-start scan line. It must be a 
numeric expression in the range 0 to 31. 


stop is the cursor-stop scan line. It also must 


be a numeric expression in the range O to 
4 
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LOCATE 
Statement 


cursor, Start, and stop do not apply to graphics mode. 


start and stop allow you to make the cursor any size “a 
you want. You indicate the starting and ending scan 

lines. The scan lines are numbered from 0 at the top 

of the character position. The bottom scan line is 7 

if you have the Color/Graphics Monitor Adapter, 13 

if you have the IBM Monochrome Display and 

Printer Adapter. If start is given and stop is omitted, 

stop assumes the value of start. If start is greater than 

stop, you'll get a two-part cursor. The cursor 

‘“‘wraps”’ from the bottom line back to the top. 


After a LOCATE statement, I/O statements to the 
screen begin placing characters at the specified 
location. 


When a program is running, the cursor is normally 
off. You can use LOCATE ,,1 to turn it back on. ~ 


Normally, the compiler does not print to line 25. 
However, if the function key display is turned off, 
using KEY OFF, you can use: 


LUCASE <cocis PRINT: .. 


to put data on line 25. Line 25 does not scroll as 
the rest of the screen does. 


Any parameter can be omitted. Omitted parameters 
assume the current value. 


Any values entered outside the ranges indicated 
results in an Illegal function call error. Previous 
values are retained. 
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Examples: 


LOCATE 
Statement 


This example moves the cursor to the home position 
in the upper left-hand corner of the screen. 


PO-LOCATE 1,1 


This example makes the blinking cursor visible; its 
position remains unchanged. 


PO LOCATE 4), 1 


In this example, position and cursor visibility remain 
unchanged. The cursor is set to display at the 
bottom of the character on the Color/Graphics 
Monitor Adapter (starting and ending on scan line 
res 


io ale, 28 en | 

This example moves the cursor to line 5, column 1. 
It makes the cursor visible, covering the entire 
character cell on the Color/Graphics Monitor 
Adapter, starting at scan line 0 and ending on scan 
line 7. 


IQ= LOCATE 5S; dame 
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LOCK 
Statement 


Purpose: — Restricts access by other processes to all or part of ‘“) 
an opened file. | 


Versions: Cartridge Disk Advanced Compiler 
* K 


Not valid for DOS versions earlier than 3.00. 
Format: LOCK [#]n [,[recnum] | TO recnum]] 
Remarks: 

n is the file number of the opened file. 


recnum _ specifies the beginning and ending record 
numbers of the range of records to be 
locked. This is only meaningful if the file ~ 
is opened for random access. 


Executing an UNLOCK statement with a DOS 
version earlier than 3.00 produces a runtime error. 


Before you run an application that uses any LOCK 
or UNLOCK statements, you must first install the 
SHARE module. This module is on the DOS disk 
and is installed by entering the command “SHARE”’ 
at the DOS prompt. 


If the file is opened for sequential access, the entire 
file is locked regardless of any range that is specified. 
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LOCK 
Statement 


If a starting record number is not specified, record 
number | is assumed. If an end record is not 
specified, only one record is locked. The range of 
legal record numbers is | to 16775616. 


Note: If locks are not removed before closing 
the file or program termination, unpredictable 
results can occur. 


See also ''UNLOCK Statement." 
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LOF 
Function 


Purpose: Returns the number of bytes allocated to the file ‘> 
(length of the file). 


Versions: Cartridge Disk Advanced Compiler 
* KK * ok * OK * KK 


Format: v = LOF(filenum) 
Remarks: 


filenum is the file number used when the file 
was opened. 


record length for random access files, the record 
length declared in the OPEN 
statement. 


For disk files created by BASIC Compiler 1.0, LOF 
returns a multiple of 128. For example, if the actual 
data in the file is 257 bytes, the number 384 is 
returned. For ASCII disk files created outside 
BASIC (for example, by using EDLIN), LOF returns 
the actual number of bytes allocated to the file. 


For communications, LOF returns the amount of 
free space in the input buffer. That is, 
size-LOC(filenum), where size is the size of the 
communications buffer, which defaults to 256 but 
can be changed with the /C: option at compile time. 
LOF can be used to detect when the input buffer is 
getting full. In practicality, LOC is adequate for this 


purpose, as demonstrated in the example in 
Appendix B, “Communications,” in BASTC “a 
Compiler 2.00 Fundamentals. 


Example: 


LOF 
Function 
These statements get the last record of the file 
named BIG (if BIG was created with a record length 
of 128 bytes): 


10 OPEN "BIG" AS #1 
20 GET #1,LOF(1)/128 


219 


LOG 


Function 
Purpose: Returns the natural logarithm of x. 
Versions: Cartridge Disk Advanced Compiler 
kK a 9k ok 9k kK 

Format: y= LOGG®) 
Remarks: 

x must be a numeric expression greater than 

Zero. 

The natural logarithm is the logarithm to the base e. 

Examples: The first example calculates the logarithm of the 
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expression 45/7: ~ 


PRINT LOG(45/7) 
Results: 


1.869752 


LOG 
Function 
The second example calculates the logarithm of e: 
PRINT LOG(E) 
Results: 
1 


The following example calculates the logarithm of 
e2: 


PRINT LOG(E*E) 
Results: 


2 
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LPOS 


Function 


Purpose: 


Versions: 


Format: 


Remarks: 


Example: 
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Returns the current position of the print head within “a 
the printer buffer for LPT1, LPT2, or LPT3. 
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y= LPS) 
n is a numeric expression that indicates the 


printer being tested, as follows: 


0 or 1 LPT: 
2 LPT2: 


3 LPT3: “~ 


Note: The colon is part of the device name and 
must be included when specifying a device. 


The LPOS function does not necessarily give the 
physical position of the print head on the printer. 


In this example, if the line length is more than 60 
characters, a carriage return character is sent to the 
printer so it skips to the next line. 


100 IF LPOS(@)>6@ THEN LPRINT CHR$(13) 


YY Purpose: 


Versions: 


Format: 


Remarks: 


LPRINT and LPRINT USING 
Statements 


Prints data on the printer (LPT1). 
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LPRINT [Jist of expressions [;] 


LPRINT USING v8; list of expressions |;] 


list of expressions 
is a list of the numeric and/or string 
expressions to be printed. The expressions 
must be separated by commas or semicolons. 


v$ is a String constant or variable that identifies 
the format to be used for printing. This is 
explained in detail under ‘““PRINT Statement.”’ 


These statements function like PRINT and PRINT 
USING, except output goes to the printer. See 
“PRINT” and “PRINT USING” statements. 


LPRINT assumes an 80-character-wide printer. 
That is, BASIC automatically inserts a carriage 
return/line feed after printing 80 characters. This 
means that two lines are skipped when you print 
exactly 80 characters, unless you end the statement 
with a semicolon. You can change the width value 
with a WIDTH “‘LPT1:”’ statement. 
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LPRINT and LPRINT USING 
Statements 


Example: 


If you do a form feed (LPRINT CHR$(12);) 
followed by another LPRINT and the printer takes 
more than 10 seconds to do the form feed, you can 
get a Device timeout error on the second LPRINT. 
To avoid this problem, enter the following: 


1 ON ERROR GOTO 65900 


65000 IF ERR = 24 THEN RESUME ‘24=timeout 


You may want to test ERL to make sure the timeout 
was caused by an LPRINT statement. 


This is an example of sending special control 
characters to the IBM Graphics Printer using 
LPRINT and CHR$. The printer control characters 
are listed in the IBM Personal Computer Technical 
Reference manual. 


1@ LPRINT CHR$(14);" Title Line" 

20 FOR I=2 TO 4 

30 LPRINT “Report line’ ;I 

49 NEXT I 

50 LPRINT CHR$(15);'Condensed print;132 
char/line" 

60 LPRINT CHR$(18);"Return to normal” 

70 LPRINT CHR$(27);'E" 

80 LPRINT "This is emphasized print” 

90 LPRINT CHR$(27);'F° 

190 LPRINT "Back to normal again” 


LPRINT and LPRINT USING 
Statements 


The output produced by this program looks like this: 


Renort Laine 2 

Flemort loirie 3 

Report Line 4 

Condensed print; 132 char/line 

Rehurn toa narmal 

This is emphasized print 


Rack to mormal again 
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LSET and RSET 
Statements 


Purpose: 


Versions: 


Format: 


Remarks: 


Moves data into a random file buffer in preparation 
for a PUT (file) statement. 
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LSET stringvar = x$ 


RSET stringvar = x$ 


stringvar is the name of a variable defined in a 
FIELD statement. 


x$ is a string expression to place the 
information into the field identified by 
stringvar. 


If x$ requires fewer bytes than were specified for 
stringvar in the FIELD statement, LSET left-justifies 
the string in the field, and RSET right-justifies the 
string. (Spaces are used to pad the extra positions. ) 
If x$ is longer than stringvar, characters are dropped 
from the right. 


Numeric values must be converted to strings before 
they are LSET or RSET. See ‘““MKI$, MKS$, 
MKD$ Functions.” 


See also ‘“‘BASIC Disk Input and Output,” in the 
BASIC Compiler 2.00 Fundamentals for a complete 
explanation of using random files. 


Example: 


LSET and RSET 
Statements 


Note: LSET or RSET can also be used with a 
string variable that was not defined in a FIELD 
statement to left-justify or right-justify a string 
in a given field. For example, the following 
program lines right-justify the string N$ in a 
20-character field. This can be useful for 
formatting printed output. 


10 A$=SPACE$(20) 
20 RSET A$=N$ 


This example converts the numeric value AMT into a 
string, and left-justifies it in the field A$ in 
preparation for a PUT (file) statement. 


18 LSET A$=MKS$(AMT ) 
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MIDS Function and 
Statement 


Purpose: 


Versions: 


Format: 


Remarks: 
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Returns the requested part of a given string. When “a 
used as a statement, as in the second format, replaces 
a portion of one string with another string. 


Cartridge Disk Advanced Compiler 


As a function: 
v$ = MID$(x$,n[,m]) 
As a statement: 


MID$(v$,n[,m]) = y$ 


For the function (v§=MIDS$...): ~ 
x$ is any string expression. 
n is an integer expression in the range 1 to 
3210 i: 
m is an integer expression in the range O to 
42767. 


The function returns a string of length m characters 
from x$ beginning with the nth character. If m is 
omitted or if fewer than m characters are to the right 
of the nth character, all rightmost characters 
beginning with the mth character are returned. If m 
is equal to 0, or if n is greater than LEN(x$), MID$ 
returns a null string. 


See also “‘“LEFT$” and “RIGHTS$” functions. “ 


MIDS Function and 


Statement 

For the statement (MID$...=y$) 

v$ is a String variable or array element that will 
have its characters replaced. 

n is an integer expression in the range 1 to 
32767. 

m is an integer expression in the range O to 
32767, 

y$ is a string expression. 


The characters in v$, beginning at position n, are 
replaced by the characters in y$. The optional m 
refers to the number of characters from y$ used in 
the replacement. If m is omitted, all of y$ is used. 


However, regardless of whether m is omitted or 
included, the length of v$ does not change. For 
example, if v$ is four characters long and y$ is five 
characters long, then after the replacement v$ 
contains only the first four characters of y§. 


Note: If either n or m is out of range, an Illegal 
function call error is returned. 
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MIDS Function and 
Statement 


Examples: The first example uses the MID$ function to select 
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the middle portion of the string B$. (> 
10 A¢="GOOD ° i 
20 B$="MORNING EVENING AFTERNOON" 

38 PRINT A$;MID$(B$,9,7) 


Results: 


‘GOOD EVENING 


The next example uses the MID$ statement to 
access substrings imbedded within one large string. 
This technique reduces fragmentation of string space. 


20° PART1..OFF: = 1 
30. PARTI -LEN==_5 
40 PART2.OFF = 6 


5@ PART2.LEN = 15 “4 


190 MID$(RECORD$,PART1.OFF,PART1.LEN) = "STRNG" 


1@ RECORD$ = STRING$(255,0) 


UU Purpose: 


Versions: 


Format: 


Remarks: 


ww Examples: 


MKDIR 
Command 


Creates a directory on the specified disk. 


Cartridge Disk Advanced Compiler 


of OK OK * KK * KK 


MKDIR path 


path is a string expression, not exceeding 63 
characters, that identifies the new directory to 
be created. For more information about paths 
refer to ““Naming Files”’ and “‘Tree-Structured 
Directories” in BASIC Compiler 2.00 
Fundamentals. 


This example creates, from the root directory, a 
subdirectory called DOS: 


MKDIR "DOS" 


This example creates, from the root directory, a 
subdirectory called DOS21 under the directory DOS: 


MKDIR "DOS\DOS21" 

This example creates, from the root directory, a 
subdirectory called DOS30 under the directory 
DOS21: 


MKDIR "DOS \DOS21 \DO0S30" 


This example creates, from the root directory, a 
subdirectory called LANG: 


MKDIR "LANG" 
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MKDIR 
Command 


This example makes LANG the current directory; 
then creates two subdirectories called BASIC and 
FORTRAN: “a 


CHDIR "LANG" 
MKDIR "BASIC" 
MKDIR “FORTRAN®™ 


The same structure can be created from the root by 
entering: 


MKDIR “LANG\ BASIC" 
MKDIR "LANG \ FORTRAN" 


The following example creates, from the root 
directory, a subdirectory called COMPILER under 
the subdirectories LANG and BASIC. 


MKDIR "“LANG\BASIC\COMPILER 


By following the above examples, you create a tree 
structure that looks like this: 


ROOT 


DOS21 DOS30 BASIC FORTRAN PASCAL 


INT COMPILER 
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ww Purpose: 


Versions: 


Format: 


Remarks: 


MKI$, MKS$, MKDS$ 
Functions 


Convert numeric type values to string type values. 


Cartridge Disk Advanced Compiler 


* KK ** KK * KK * KOK 


v$ = MKI$(integer expression) 
v$ = MKS$(single-precision expression) 
v$ = MKD$(double-precision expression) 


Any numeric value that is placed in a random file 
buffer with an LSET or RSET statement must be 
converted to a string. MKI$ converts an integer to a 
2-byte string. MKS$ converts a single-precision 
number to a 4-byte string. MKD$ converts a 
double-precision number to an 8-byte string. 


These functions differ from STR$ because they do 
not really change the bytes of the data—just the way 
BASIC interprets those bytes. 


See also “CVI, CVS, CVD Functions” in this 
manual and “BASIC Disk Input and Output,” in 
BASIC Compiler 2.00 Fundamentals. 


MKI$, MKS$, MKD$ 
Functions 


Example: This example uses a random file (#1), that has 
previously been opened, with the fields defined in 
line 100. The first field, D$, is intended to hold a (> 
numeric value, AMT. Line 110 converts AMT toa 
string value using MKS$ and uses LSET to place 
what is really the value of AMT into the random file 
buffer. Line 120 places a string into the buffer (it is 
not necessary to convert a string). Line 130 writes 
the data from the random file buffer to the file. 


190 FIELD #1, 4 AS D$, 20 AS N$ 
119 LSET D$ = MKS$(AMT) 

120 LSET N$ = A$ 

130 PUT #1 
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wy Purpose: 


Versions: 


Format: 


Remarks: 


Example: 


MOTOR 
Statement 


Turns the cassette player on and off. 


Cartridge Disk Advanced Compiler 


OK * KOK > KOK * KK 


MOTOR [state] 


state is a numeric expression indicating on or 
off. 


If state is nonzero, the cassette motor is turned on. If 
state is zero, the cassette motor is turned off. 


If state is omitted, the cassette motor state is 
switched. That is, if the motor is off, it is turned on 
and vice versa. 


The following sequence of statements turns the 
cassette motor on, then off, then back on again. 


1% MOTOR 1 
20 MOTOR @ 
38 MOTOR 
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NAME 
Command 


Purpose: Changes the name of a disk file. The NAME ‘> 
command in BASIC is similar to the RENAME 
command in DOS. 


Versions: Cartridge Disk Advanced Compiler 
** K 2 OK * OK * KK 


Format: NAME /filespec AS [path| filespec 
Remarks: 


filespec is a string expression for the file 
specification. It can contain a path and 
must conform to the rules outlined 
under ‘“‘Naming Files” in BASIC 
Compiler 2.00 Fundamentals, 
otherwise, a Bad file name error occurs. 


path is a path to any directory on the drive 
specified in filespec. You cannot 
rename across drives. name with a path 
is essentially the same as copying and 
deleting a file, except that the file is not 
moved; only its directory entry is 
changed. 


The file specified by filespec must exist and filename 
must not exist on the disk; otherwise, an error 
results. 


Both files must be on the same physical drive, or you 
will get a File already exists error. Different logical 
devices, using the DOS “‘ASSIGN” Statement, are 
allowed. If the device name is omitted, the DOS 
default drive is assumed. Note that the file extension 
does not default to .BAS. 
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NAME 
Command 


After a NAME command, the file exists on the same 
disk, in the same disk space, with the new name. 


In this example, the file that was formerly named 
ACCTS.BAS on the disk in drive A is now named 
LEDGER.BAS. 


NAME "A:ACCTS.BAS" AS "LEDGER.BAS" 


NOISE 
Statement 


Purpose: Generates noise through the external speaker. ‘> 


Versions: Cartridge Disk Advanced Compiler 
** K * KK 


Format: NOISE source, volume, duration 


Remarks: 
source is the noise source. It is a numeric 
expression in the range O to 7. If source is 
in the range O to 3, periodic noise is 
selected. If source is in the range 4 to 7, 
white noise is selected. 
Periodic White Source is Clock Frequency 
(3.579) “A 
0 4 3.579/512 (high pitch, less 
coarse hiss) 
1 5 3.579/1024 
2 6 3.579/2048 (low pitch, more 
coarse hiss) 
3 ‘ source is frequency from voice 3 


Note that for source values of 3 and 7, the frequency 
of voice 3 is used instead of the system clock. The 
voice 3 frequency can be set by the PLAY statement 
or the SOUND statement. 


volume _ iS a numeric expression in the range 0 to “ 
1S: 
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Example: 


NOISE 
Statement 


duration is the desired duration in clock ticks. The 
clock ticks occur 18.2 time per second. 
duration must be a numeric expression in 
the range O to 65535. 


Sound produced by the NOISE statement goes to the 
external speaker. A SOUND ON statement must be 
executed before using NOISE or you get an Illegal 
function call error. 


If you want to use a noise source of 3 or 7, refer to 
the ““PLAY Statement” and the “SOUND 
Statement”’ for information on multiple voices. 


This example demonstrates all seven noise sources. 
Note the use of three voices with the PLAY 
statement. 


100 SOUND ON 

110 FOR N=@ TO 7 

130 NOISE N,15,250 

140 PLAY ee 

150 FOR I=1 TO 6 

160°-PLAY oS eee FVARPTRS(1)4" TZ55CDEF- 
170 NEXT I 

180 NEXT N 
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OCTS$ 
Function 


Purpose: Returns a string that represents the octal value of the ‘> 
decimal argument. 


Versions: Cartridge Disk Advanced Compiler 
* KK 7 K * kK * K 


Format: v$ = OCTS$(n) 
Remarks: 


n is a numeric expression in the range -32768 to 
GIFs: 


If n is negative, the twos complement form is used. 
That is, OCT$(-n) is the same as OCT$(65536-n). 


See ““HEX$ Function” for hexadecimal conversion. ty 
Example: This example shows that 24 in decimal is 30 in octal. 
PRINT OCT$(24) 


Results: 


30 
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ON COM(n) 
Statement 


iY Purpose: Sets up a line number or label for BASIC to branch 
to when there is information coming into the 
communications buffer. 


Versions: Cartridge Disk Advanced Compiler 


Format: ON COM(n) GOSUB line | label 


Remarks: 


n is the number of the communications adapter 
(1 or 2). 


line is the line number of the beginning of the trap 
routine. Setting /ine equal to zero disables 
trapping of communications activity for the 
specified adapter. 


label is asequence of 1 to 40 letters, digits, or 
periods, in any combination, followed by a 
colon. 


The use of mnemonic labels makes your 
programs easier to read and maintain. Labels 
can be used as objects of most statements 
where line numbers are currently permitted, 
with the following exceptions: 


IF (condition) THEN (line number) 


and 


Ww RUN (line number) 
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ON COM(n) 
Statement 


In each of these cases, only a line number is 
permitted in the statement. However, for 

both of these cases, the explicit use of a ‘> 
GOTO statement allows a label to be used. 

For example: 


IF A>10 THEN GOTO BAD.DATA 


To distinguish labels from keywords or 
variables, each label must be followed by a 
colon (:) when it starts a line. 


Note: If you wish to use error reporting 
(with the /E option) and error trapping, 
you must use line numbers. 


Numeric labels, alphanumeric labels, and line 
numbers can be intermixed in the same 
program, and numeric or alphanumeric labels 
may be used without the /N switch. 


A COM(n) ON statement must be executed to 
activate this statement for adapter n. After COM(n) 
ON, if a nonzero line number is specified in the ON 
COM(n) statement, then every time the program 
starts a new statement or line, (depending on 
whether you compiled using /V or /W), BASIC 
checks to see if any characters have come in to the 
specified communications adapter. If so, BASIC 
performs a GOSUB to the specified /ine or label. 


Note: If your program contains any 
event-trapping statements, such as ON COM, 
for example, you need to compile your program 
using the /V or /W switch. 


Note: If you compile your program with the /O * 
switch, you must link the IBMCOM.OBJ 
module. 
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ON COM(n) 
Statement 


If COM(n) OFF is executed, no trapping takes place 
for the adapter. Even if communications activity 
does take place, the event is not remembered. 


If a COM(n) STOP statement is executed, no 
trapping takes place for the adapter. However, any 
characters being received are remembered so an 
immediate trap takes place when COM(n) ON is 
éxecuted. 


When the trap occurs, an automatic COM(n) STOP 
is executed so that recursive traps never take place. 
The RETURN from the trap routine automatically 
does a COM(n) ON unless an explicit COM(n) OFF 
was performed inside the trap routine. 


When an error trap takes place, all trapping is 
automatically disabled (including ON COM, ON 
ERROR, ON PEN, ON PLAY, ON STRIG, and ON 
TIMER). 


Typically, the communications trap routine reads an 
entire message from the communications line before 
returning. It is not recommended that you use the 
communications trap for single character messages, 
since at high baud rates the overhead of trapping and 
reading for each individual character allows the 
interrupt buffer for communications to overflow. 


You can use RETURN ine | label if you want to go 
back to the BASIC program at a fixed line number or 
label. This nonlocal return must be used with care, 
however, since any other GOSUBs, WHILEs, or 
FORs active at the time of the trap remain active. 
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ON COM(n) 
Statement 


Active loops are exited by setting the loop counter 

variable out of range or setting a conditional 

Statement within the loop to terminate it. This ‘y 
insures that every iteration of a FOR has a 

corresponding NEXT and every iteration of a 

WHILE has a corresponding WEND. 


Example: This example sets up a trap routine for the first 
communications adapter at line 500. 


158 ON COM(1) GOSUB 500 
16@ COM(1) ON 


900 ‘incoming characters 


590 RETURN 300 
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ON ERROR 
Statement 


oe Purpose: Sets up a line number or label for BASIC to branch 
to when an error occurs. 


Versions: Cartridge Disk Advanced Compiler 


Format: ON ERROR GOTO Iine | label 
Remarks: 
line is the line number of the first line of the error 
trapping routine. If the line number does not 
exist, an Undefined line number error results. 
label is asequence of 1 to 40 letters, digits, or 


periods, in any combination, followed by a 
colon. 


The use of labels allows the use of mnemonic 
labels to make your programs easier to read 
and maintain. Labels can be used as objects 
of most statements where line numbers are 
currently permitted, with the following 
exceptions: 


IF (condition) THEN (line number) 
and 


RUN Jine number) 


ON ERROR 
Statement 


In these cases, only a line number is permitted 

in the statement. However, for both cases, 

the explicit use of a GOTO statement allows a (‘> 
label to be used. For example: , 


IF A>10 THEN GOTO BAD.DATA 


To distinguish labels from keywords or 
variables, each label must be followed by a 
colon (:) when it starts a line. 


Note: If you wish to use error reporting 
(with the ERL variable ) and error 
trapping, you must use line numbers. 


Numeric labels, alphanumeric labels, and line 
numbers can be intermixed in the same 

program, and numeric or alphanumeric labels 
may be used without the /N switch. “ 


Once error trapping has been enabled, all errors 
detected cause a jump to the specified error handling 
subroutine. 


Note: If your program contains any ON 
ERROR or RESUME statements, you may need 
to compile using the /X or /E parameter. See 
‘‘Compiler Parameters” in BASIC Compiler 
2.00 Fundamentals for more information. 


To disable error trapping, execute an ON ERROR 
GOTO O. Subsequent errors print an error message 
and halt execution. An ON ERROR GOTO 0 
statement that appears in an error trapping 
subroutine causes BASIC to stop and print the error 
message for the error that caused the trap. It is - 
recommended that all error-trapping subroutines 

execute an ON ERROR GOTO 0 if an error is 

encountered for which there is no recovery action. 
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w Example: 


ON ERROR 
Statement 


BASIC considers itself to be within the error 
trapping routine from the time an error occurs. It 
branches to the line specified by the ON ERROR 
statement untila RESUME statement is 
encountered. You must use the RESUME statement 
to exit from the error trapping routine. See also 
‘““RESUME Statement.”’ 


Because error trapping does not occur within the 
error trapping routine, an ON ERROR GOTO line 
(within the error trapping routine), where /ine is 
anything other than 0, does not work. 


Note: If an error occurs during execution of an 
error handling subroutine, the BASIC error 
message is printed and execution terminates. 
Error trapping does not occur within the error 
handling subroutine. 


This example tests to see if the drive door is open 
when the program needs to open a file. 


19 ON ERROR GOTO 1090 
20 OPEN "DATA" FOR INPUT AS #1 
30 END 


190 IF ERR=71° PHER: COCATE 23.1: 
PRINT "DISK IS NOT READY" 
11@ RESUME NEXT 
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ON...GOSUB and ON...GOTO 
Statements 


Purpose: Branches to one of several specified line numbers or 
labels depending on the value of an expression. 


Versions: Cartridge Disk Advanced Compiler 


(**) (**) (**) 4K 
Format: ON n GOTO line | label |,line| label |... 

ON n GOSUB [ine | label [, line | label |... 
Remarks: 


n is a numeric expression, rounded to an 
integer, if necessary. It must be in the range O 
to 255, or an Illegal function call error occurs. 


line is the number of the line to which the ‘o) 
program branches. 


label is asequence of 1 to 40 letters, digits, or 
periods, in any combination, followed by a 
colon. 


The use of labels allows the use of mnemonic 
labels to make your programs easier to read 
and maintain. Labels can be used as objects 
of most statements where line numbers are 
currently permitted, with the following 
exceptions: 


IF (condition) THEN (line number) 


and “a 


RUN (line number) 
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ON...GOSUB and ON...GOTO 
Statements 


In each of these cases, only a line number is 
permitted in the statement. However, for 

& both of these cases, the explicit use of a 
GOTO statement allows a label to be used. 
For example: 


IF A>10 THEN GOTO BAD.DATA 


To distinguish labels from keywords or 
variables, each label must be followed by a 
colon (:) when it starts a line. 


Note: If you wish to use error reporting 
(with the /E option) and error trapping, 
you must use line numbers. 


Numeric labels, alphanumeric labels, and line 
numbers can be intermixed in the same 

Y& program, and numeric or alphanumeric labels 
may be used without the /N switch. 


The value of n determines which line number in the 
list the program uses for branching. For example, if 
the value of n is 3, the third line number in the list is 
the point at which the program branches. 


In the ON...GOSUB statement, each line number in 
the list must be the first line number of a subroutine. 
Eventually you must have a RETURN statement to 
bring you back to the line following the 
ON...GOSUB. 


If the value of n is zero, or greater than the number 
of items in the list (but less than or equal to 255), 
BASIC continues with the next executable 

Y statement. 
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ON...GOSUB and ON...GOTO 
Statements 


Examples: The first example branches to line 150 if L-1 equals 
1; to line 300 if L-1 equals 2; to line 320 if L-1 
equals 3; and to line 390 if L-1 equals 4. If L-1 is ‘> 
equal to 0, or is greater than 4, the program just goes 
on to the next statement. 


199 ON L-1 GOTO 159,300 ,320,390 


The next example shows how to use an 
ON...GOSUB statement. 


180 REM display menu 

110 PRINT "1. Routine 1" 

120 PRINT "2. Routine 2" 

130 PRINT "3. Routine 3°" 

149 PRINT "4. Routine 4" 

150 INPUT "Your choice?"; CHOICE 

16@ ON CHOICE GOSUB 200, 300, 400, 500 

178 GOTO 190 ' redisplay menu after routine is done 

200 REM start of first routine “ 


290 RETURN 
300 REM start of second routine 
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w Purpose: 


Versions: 


Format: 


Remarks: 


ON KEY(n) 
Statement 


Sets up a line number or label for BASIC to branch 
to when the specified function key or cursor control 
key is pressed. 


Cartridge Disk Advanced Compiler 


ON KEY(n) GOSUB line | label 


n is a numeric expression in the range 1 to 2@ 
indicating the key to be trapped, as follows: 


1-10 Function keys F1 to F10 

11 Cursor Up 

12 Cursor Left 

13 Cursor Right 

14 Cursor Down 

15-20 keys defined by the form: 
KEY n,CHR$(KBflag)+CHRS$(scan code). 
See ‘““KEY(n) Statement” for more 
information. 


line is the line number of the beginning of the 
trapping routine for the specified key. Setting 
line equal to O stops trapping of the key. 


label is asequence of 1 to 40 letters, digits, or 
periods, in any combination, followed by a 
colon. 


ON KEY(n) 
Statement 


The use of mnemonic labels makes your 

programs easier to read and maintain. Labels 

can be used as objects of most statements ry 
where line numbers are currently permitted, 

with the following exceptions: 


IF (condition) THEN (line number) 
and. 
RUN (line number) 


In each of these cases, only a line number is 
permitted in the statement. However, for 
both of these cases, the explicit use of a 
GOTO statement allows a label to be used. 
For example: 


IF A>10 THEN GOTO BAD.DATA “ 


To distinguish labels from keywords or 
variables, each label must be followed by a 
colon (:) when it starts a line. note. If you 
wish to use error reporting (with the /E 
option) and error trapping, you must use line 
numbers. 


Numeric labels, alphanumeric labels, and line 
numbers can be intermixed in the same 
program, and numeric or alphanumeric labels 
may be used without the /N switch. 
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ON KE Y(n) 
Statement 


A KEY(n) ON statement must be executed to 
activate this statement. After KEY(n) ON, if a 
nonzero line number is specified in the ON KEY(n) 
statement, then every time the program starts a new 
statement or line number (depending on whether the 
program was compiled with /V or /W), BASIC 
checks to see if the specified key was pressed. If so, 
BASIC performs a GOSUB to the specified /ine or 
label. 


Note: If your program contains any 
event-trapping statements, such as ON KEY, for 
example, you need to compile your program 
using the /V or /W switch. 


If a KEY(n) OFF statement is executed, no trapping 
takes place for the specified key. Even if the key is 
pressed, the event is not remembered. 


If a KEY(n) STOP statement is executed, no 
trapping takes place for the specified key. However, 
if the key is pressed, the event is remembered, so an 
immediate trap takes place when KEY(n) ON is 
executed. 


When the trap occurs, an automatic KEY(n) STOP is 
executed so that recursive traps never take place. 
The RETURN from the trap routine automatically 
does a KEY(n) ON unless an explicit KEY(n) OFF 
was performed inside the trap routine. 


Key trapping may not work if you press other keys 
before the specified key. The key that caused the 
trap cannot be tested using INPUT$ or INKEY$, so 
the trap routine for each key must be different if a 
different function is desired. 


ON KEY(n) 
Statement 


Examples: 
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You can use RETURN line | label if you want to go 
back to the BASIC program at a fixed line number or 
label. This nonlocal return must be used with care, 
however, since any other GOSUBs, WHILEs, or 
FORs active at the time of the trap remain active. 


Active loops are exited by setting the loop counter 
variable out of range or setting a conditional 
statement within the loop to terminate it. This 
ensures that every iteration of a FOR has a 
corresponding NEXT and every iteration of a 
WHILE has a corresponding WEND. 


KEY(n) ON has no effect on whether the soft key 
values are displayed at the bottom of the screen. 


The following is an example of a trap routine for 
function Key 5. 


198 ON KEY(5) GOSUB 200 
119 KEY(5) ON 


200° ‘function key 5 pressed 


299 RETURN 149 


ON KEY(n) 
Statement 


This example traps Ctrl-Break and Ctrl-Alt-Del. It 
assumes that Caps Lock, and Num Lock are 
currently disabled. 


10 KEY 15,CHR$(&H@4)+CHR$(7@) ‘Trap Ctr1-Break 
20 KEY 16,CHR$(&HQ4+&H@8 ) +CHR$ (83) 
‘Trap Ctr1-Alt-Del 
38 ON KEY(15) GOSUB 1090 
40 ON KEY(16) GOSUB 2000 
5@ KEY(15) ON: KEY(16) ON 


1000 PRINT "Trapping for Ctr1-Break" 

191@ RETURN 

2000 TRAPS=TRAPS+1 

2010 ON TRAPS GOTO 2100,2200,2300,2400, 2500 
2020 ' 

2100 PRINT "First trap of System Reset":RETURN 
2200 PRINT "Second trap of System Reset":RETURN 
2300 PRINT "Third trap of System Reset":RETURN 
2400 PRINT "Fourth trap of System Reset":RETURN 
2500 KEY(16) OFF ‘Disable trap of System Reset 


Note: When specifying scan codes, you can use 
either hexadecimal or decimal notation. 
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ON PEN 
Statement 


Purpose: Sets up a line number or label for BASIC to branch 
to when the light pen is activated. 


Versions: Cartridge Disk Advanced Compiler 


Format: ON PEN GOSUB [ine | label 


Remarks: 


line is the line number of the beginning of the trap 
routine for the light pen. Using a line number 
of O disables trapping of the light pen. 


label is asequence of 1 to 40 letters, digits, or 
periods, in any combination, followed by a 
colon. “ 


The use of mnemonic labels makes your 
programs easier to read and maintain. Labels 
can be used as objects of most statements 
where line numbers are currently permitted, 
with the following exceptions: 


IF (condition) THEN (line number) 
and 


RUN (dine number) 
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ON PEN 
Statement 


In each of these cases, only a line number is 
permitted in the statement. However, for 
both of these cases, the explicit use of a 
GOTO statement allows a label to be used. 
For example: 


IF A>10 THEN GOTO BAD.DATA 


To distinguish labels from keywords or 
variables, each label must be followed by a 
colon (:) when it starts a line. 


Note: If you wish to use error reporting 
(with the /E option) and error trapping, 
you must use line numbers. 


Numeric labels, alphanumeric labels, and line 
numbers can be intermixed in the same 
program, and numeric or alphanumeric labels 
may be used without the /N switch. 


A PEN ON statement must be executed to activate 
this statement. After PEN ON, if a nonzero line 
number is specified in the ON PEN statement, then 
every time the program starts a new statement 
BASIC checks to see if the pen was activated. If so, 
BASIC performs a GOSUB line | label. 


If PEN OFF is executed, no trapping takes place. 
Even if the light pen is activated, the event is not 
remembered. 


If a PEN STOP statement is executed, no trapping 
takes place, but pen activity is remembered so that 
an immediate trap takes place when PEN ON is 

executed. 


ON PEN 
Statement 


When the trap occurs, an automatic PEN STOP is 
executed so recursive traps never take place. The 
RETURN from the trap routine automatically does a yy 
PEN ON unless an explicit PEN OFF was performed ‘ 
inside the trap routine. 


PEN(O) is not set when pen activity causes a trap. 


You can use RETURN Jine | label if you want to go 
back to the BASIC program at a fixed line number. 
This nonlocal return must be used with care, 
however, since any other GOSUBs, WHILEs, or 
FORs active at the time of the trap remain active. 


Active loops are exited by setting the loop counter 

variable out of range or setting a conditional 

statement within the loop to terminate it. This 

insures that every iteration of a FOR has a 

corresponding NEXT and every iteration of a - 
WHILE has a corresponding WEND. 


Example: This example sets up a trap routine for the light pen. 


19 ON PEN GOSUB 59@@ 
20 PEN ON 


500 ‘subroutine for pen 


650 RETURN 39 


258 


ON PLAY(n) 
Statement 


YY Purpose: Sets up a line number or label for BASIC to branch 
to when the music background buffer has gone from 
nto n-J1. during program execution. 


Versions: Cartridge Disk Advanced Compiler 


Format: ON PLAY(n) GOSUB [ine | label 


Remarks: 

n is an integer expression in the range 1 to 32 
indicating the notes to be trapped. Values 
entered outside this range result in an Illegal 
function call error. 

yy line is the beginning line number of the trap 


routine for PLAY. A line number of 0 stops 
the trapping of PLAY. 


label is asequence of 1 to 40 letters, digits, or 
periods, in any combination, followed by a 
colon. 


The use of mnemonic labels makes your 
programs easier to read and maintain. Labels 
can be used as objects of most statements 
where line numbers are currently permitted, 
with the following exceptions: 


IF (condition) THEN (line number) 


u - 


RUN (line number) 
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ON PLAY(n) 
Statement 


In each of these cases, only a line number is 
permitted in the statement. However, for 
both of these cases, the explicit use of a 
GOTO statement allows a label to be used. 
For example: 


IF A>10 THEN GOTO BAD.DATA 


To distinguish labels from keywords or 
variables, each label must be followed by a 
colon (:) when it starts a line. 


Note: If you wish to use error reporting 
(with the /E option) and error trapping, 
you must use line numbers. 


Numeric labels, alphanumeric labels, and line 
numbers can be intermixed in the same 

program, and numeric or alphanumeric labels ~ 
may be used without the /N switch. 


A PLAY ON statement must be used to start the ON 
PLAY(n) statement. You can then play continuous 
background music during program execution. (See 
“PLAY Statement.”) After PLAY ON, if a nonzero 
line number is specified in the PLAY(n) statement, 
each time the program starts a new statement or line 
number (depending on whether you compiled using 
/V or /W), BASIC checks to see if the music buffer 
has gone from 7 to n-1 notes. If so, BASIC performs 
a GOSUB to the specified line or label. 


Note: If your program contains any 

event-trapping statements, such as ON PLAY, 

for example, you need to compile your program 

using the /V or /W switch. “» 
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ON PLAY(n) 
Statement 


If PLAY OFF is used, no trapping takes place. Even 
if a play activity takes place, the event is not 
remembered. 


If a PLAY STOP statement is used, no trapping 
takes place, but play activity is remembered so that 
an immediate trap takes place when PLAY ON is 
executed. 


When the trap occurs, an automatic PLAY STOP is 
run so recursive traps never take place. The 
RETURN from the trap routine automatically does a 
PLAY ON unless an explicit PLAY OFF was 
performed inside the trap routine. 


You can use RETURN ine | label if you want to go 
back to the BASIC program at a fixed line number or 
label. This nonlocal return must be used with care, 
& however, since any other GOSUBs, WHILEs, or 
FORs active at the time of the trap remain active. 


Active loops are exited by setting the loop counter 
variable out of range or setting a conditional 
statement within the loop to terminate it. 


Notes: 


1. A PLAY event trap is issued only when PLAY 
is in the Music Background mode (PLAY 
‘““MB...’’). An event trap is not issued when 
PLAY is in the Music Foreground mode (PLAY 
“ME... D. 


2. A PLAY event trap is not issued if the Music 


& Background buffer is already empty when a 
PLAY ON statement is performed. 
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ON PLAY(n) 
Statement 


3. Be careful choosing values for n. For example: 
ON PLAY(32) causes so many event traps that 
little time remains to run the rest of the ‘oe 


program. 


See also ‘““PLAY(n) Function”’ for additional 
information. 


Example: This example sets up a trap routine that is invoked 


when five notes are left in the background music 
buffer. 


19 ON PLAY(5) GOSUB 509 | 
20 PLAY ON ~ 


500° ‘subroutine for background music 


650 RETURN 30 
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‘eo Purpose: 


Versions: 


Format: 


Remarks: 


ON STRIG(n) 
Statement 


Sets up a line number or label for BASIC to branch 
to when one of the joystick buttons (triggers) is 
pressed. 


Cartridge Disk Advanced Compiler 


ON STRIG(n) GOSUB line | label 


n can be O, 2, 4, or 6, and indicates the button 
to be rapped as follows: 


0 button Al 
2 button Bl 
4 button A2 
6 button B2 

line is the line number of the beginning of the trap 
routine for STRIG. A line number of O stops 
trapping of the joystick button. 

label is asequence of 1 to 40 letters, digits, or 


periods, in any combination, followed by a 
colon. 
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ON STRIG(n) 
Statement 


The use of mnemonic labels makes your 
programs easier to read and maintain. Labels 
can be used as objects of most statements 
where line numbers are currently permitted, 
with the following exceptions: 


IF (condition) THEN (line number) 
and 
RUN (line number) 


In each of these cases, only a line number is 
permitted in the statement. However, for 
both of these cases, the explicit use of a 
GOTO statement allows a label to be used. 
For example: 


IF A>10 THEN GOTO BAD.DATA “a 


To distinguish labels from keywords or 
variables, each label must be followed by a 
colon (:) when it starts a line. 


Note: If you wish to use error reporting 
(with the /E option) and error trapping, 
you must use line numbers. 


Numeric labels, alphanumeric labels, and line 
numbers can be intermixed in the same 
program, and numeric or alphanumeric labels 
may be used without the /N switch. 
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ON STRIG(n) 
Statement 


A STRIG(n) ON statement must be executed to 
activate this statement for button n. If STRIG(n) ON 
is executed and a nonzero line number is specified in 
the ON STRIG(n) statement, then every time the 
program starts a new statement BASIC checks to see 
if the specified button has been pressed. If so, 
BASIC performs a GOSUB to the specified line or 
label. 


Note: If your program contains any 
event-trapping statements, such as ON STRIG, 
for example, you may need to compile your 
program using the /V or /W switch. 


If STRIG(n) OFF is executed, no trapping takes 
place for button n. Even if the button is pressed, the 
event is not remembered. 


If a STRIG(n) STOP statement is executed, no 
trapping takes place for button n, but the button 
being pressed is remembered so that an immediate 
trap takes place when STRIG(n) ON is executed. 


When the trap occurs, an automatic STRIG(n) STOP 
is executed so that recursive traps never take place. 
The RETURN from the trap routine automatically 
does a STRIG(n) ON unless an explicit STRIG(n) 
OFF was performed inside the trap routine. 


Using STRIG(n) ON activates the interrupt routine 
that checks the button status for the specified 
joystick button. Downstrokes that cause trapping do 
not set functions STRIG(0), STRIG(2), STRIG(4), 
or STRIG(6). 


ON STRIG(n) 
Statement 


You can use RETURN ine | label to go back to the 
BASIC program at a fixed line number. This 
nonlocal return must be used with care, however, 
since any other GOSUBs, WHILEs, or FORs active 
at the time of the trap remain active. 


Active loops are exited by setting the loop counter 
variable out of range or setting a conditional 
statement within the loop to terminate it. This 
insures that every iteration of a FOR has a 
corresponding NEXT and every iteration of a 
WHILE has a corresponding WEND. 


Example: This is an example of a trapping routine for the 
button on the first joystick. 


18 ON STRIG(@) GOSUB 509 
20 STRIG(@) ON 


590 ‘subroutine for lst button 


650 RETURN 
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ON TIMER 
Statement 


Y Purpose: — Branches to a given line number or label in a BASIC 
program when a defined period of time has elapsed. 


Versions: Cartridge Disk Advanced Compiler 


Format: ON TIMER(n) GOSUB [ine | label 


Remarks: 


n is a numeric expression in the range 1 to 
86400 (1 second through 24 hours). Values 
entered that are outside this range result in an 
Illegal function call error. 


line is the beginning line number of the trap 
routine for TIMER. A line number of 0 stops 
timer trapping. 


label is asequence of 1 to 40 letters, digits, or 
periods, in any combination, followed by a 
colon. 


The use of mnemonic labels makes your 
programs easier to read and maintain. Labels 
can be used as objects of most statements 
where line numbers are currently permitted, 
with the following exceptions: 

IF (condition) THEN (line number) 


and 


w RUN (dine number) 


267 


ON TIMER 
Statement 


In each of these cases, only a line number is 
permitted in the statement. However, for 

both of these cases, the explicit use of a ‘ty 
GOTO statement allows a label to be used. : 
For example: 


IF A>10 THEN GOTO BAD.DATA 


To distinguish labels from keywords or 
variables, each label must be followed by a 
colon (:) when it starts a line. note. If you 
wish to use error reporting (with the /E 
option) and error trapping, you must use line 
numbers. 


Numeric labels, alphanumeric labels, and line 
numbers can be intermixed in the same 

program, and numeric or alphanumeric labels 

may be used without the /N switch. ~ 


A TIMER ON statement must be used to start the 
ON TIMER statement. (See ‘““TIMER Statement’’). 
After TIMER ON, if a nonzero line number is 
specified in the ON TIMER statement, then every 
time the program starts a new statement or line 
number, (depending on whether you compiled using 
/V or /W), BASIC checks to see if the specified 
number of seconds have passed. When n seconds 
have elapsed, BASIC performs a GOSUB to the 
specified line. The event trap occurs, and BASIC 
starts counting again from 0. 


Note: If your program contains any 
event-trapping statements, such as ON TIMER, 
for example, you need to compile your program 


using the /V or /W switch. a 
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ON TIMER 
Statement 


If TIMER OFF is used, no trapping takes place. 
Even if TIMER activity takes place, the event is not 
remembered. 


If a TIMER STOP statement is used, no trapping 
takes place, but TIMER activity is remembered so 
that an immediate trap occurs when TIMER ON is 
used. 


When the trap occurs, an automatic TIMER STOP is 
executed so that recursive traps never take place. 
The RETURN from the trap routine automatically 
does a TIMER ON unless an explicit TIMER OFF 
was performed inside the trap routine. 


You can use RETURN line | label to go back to the 
BASIC program at a fixed line number. This 
nonlocal return must be used with care, however, 
since any other GOSUBs, WHILEs, or FORs active 
at the time of the trap remain active. 


Active loops are exited by setting the loop counter 
variable out of range or setting a conditional 
statement within the loop to terminate it. This 
insures that every iteration of a FOR has a 
corresponding NEXT and every iteration of a 
WHILE has a corresponding WEND. 
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ON TIMER 
Statement 


Example: ON TIMER is useful in programs that need an 
interval timer. This example displays the time of day 
on line 1 every minute. 


19 CLS 
20 ON TIMER(6@) GOSUB 19900 
30 TIMER ON 


19090 OLDROW=CSRLIN ‘save current row 

19910 OLDCOL=POS(@) ‘save current column 
19020 LOCATE 1,1:PRINT TIME$; 

19030 LOCATE OLDROW,OLDCOL ‘restore row & col 
190490 RETURN 
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Purpose: 


Versions: 


Format: 


Remarks: 


OPEN 
Statement 


Allows input or output to a file or device. 


Cassette 


Disk Advanced Compiler 


OPEN /filespec [FOR mode| |ACCESS access | 
[locking| AS [#] filenum |LEN= rec! | 


filespec 


mode 


OUTPUT 


INPUT 
APPEND 


RANDOM 


is a String expression for the file 
specification. It can contain a path and 
must conform to the rules outlined under 
“Naming Files’ in BASIC Compiler 
Fundamentals, otherwise, a Bad file 
name error occurs. 


is one of the following: 

specified sequential output mode. 
Warning: Opening a sequential file 
for output destroys the contents of 
the file. 

specifies sequential input mode. 

specifies sequential output mode where 

the file is positioned to the end of data 

on the file when it is opened. 

specified random input or output mode. 

Note that mode must be a string 

constant, not enclosed in quotation 


marks. If mode is omitted, random 
access 1S assumed. 
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OPEN 


Statement 
access is one of the following: 
READ allows file access for input only. 


WRITE allows file access for output only. 


READ WRITE 
allows file access for input and output. 


locking is one of the following: 


SHARED Any process on any machine may have 
read or write access to the file. 


LOCK READ 
No other process is to be granted read 
access to this file. This access is granted 
only if no other process has locked read 
access to the file. 


LOCK WRITE a 


No other process is to be granted write 
access to this file. This access is granted 
only if no other process has locked write 
access to the file. 


pa 9? 


OPEN 
Statement 


LOCK READ WRITE 
No other process is to be granted read or 
write access to this file. This access is 
granted only if no other process has locked 
read or write access to the file. 


If locking is not specified, the file may be opened for 
reading and writing any number of times by the 
process, but other processes are denied access to this 
file while it is opened. 


File access control is provided to support a networking 
environment. If you are not familiar with this type of 
environment, you should understand that file access 
must be strictly controlled to protect the integrity of 
data files that are accessible by several people. Data 
loss can occur when two or more people attempt to 
access the same file simultaneously. By using the file 
access and locking parameters, control can be 
established and data loss or corruption can be 
minimized. See the DOS Technical Reference for the 
Share Matrix DOS 3.0/3.1. 


The following example opens a file for input and 
denies write access to all other processes. 


10 OPEN "TEST.DAT" FOR INPUT LOCK WRITE AS #1 
20 INPUT #1,A$ 
30 CLOSE #1 


Note: You must use DOS 3.0 or later and 


SHARE if you want to use the new OPEN 
access and locking parameters. 
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OPEN 
Statement 


For both formats: 


filenum 


filespec 


recl 
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is an integer expression whose value is 
between | and 255. 


Note: See “Building a BASIC 
Source Program” in BASIC 
Compiler 2.00 Fundamentals for 
detailed information on the number 
of files allowed. 


is a string expression for the file 
specification. It can contain a path and 
must conform to the rules outlined under 
‘““Naming Files” in BASIC Compiler 
2.00 Fundamentals, otherwise, a Bad 
file name error occurs. 


is an integer expression which, if 

included, sets the record length for -) 
random files. It can range from 1 to | 
32767. The default record length is 128 

bytes. 


OPEN 
Statement 


OPEN allocates a buffer for I/O to the file or device 
and determines the mode of access that is used with 
the buffer. 


filenum is the number that is associated with the file 
or device for as long as it is open and is used by 
other I/O statements to refer to the file or device. 


An OPEN must be executed before any I/O can be 
done to a device or file using any of the following 
statements, or any statement or function requiring a 
file number: 


PRINT # WRITE # 
PRINT # USING INPUT$ 
INPUT # GET # 
LINE INPUT # PUT# 
IOCTL # 


GET and PUT are valid for random files or 
communications files. A disk file can be either 
random or sequential, and a printer can be opened in 
either random or sequential mode; however, all other 
standard devices can be opened only for sequential 
operations. See “OPEN “COM... Statement.”’ 


OPEN 
Statement 


BASIC normally adds a line feed after each carriage 
return (CHR$(13)) sent to a printer. However, if 

you open a printer (LPT1:,LPT2:, or LPT3:) asa ‘> 
random file with width 255, this line feed is 
suppressed. 


APPEND is valid only for disk files. The file pointer 
is initially set to the end of the file, and the record 
number is set to the last record of the file. PRINT # 
or WRITE # then extends the file. 


A file cannot be opened for sequential output or 
append if the file is already open. 


If a file opened for input does not exist, a File not 
found error occurs. If a file that does not exist is 
opened for output, append, or random access, a file 
is created. 


Any values given outside the ranges indicated result 
in an Illegal function call error. The file is not 
opened. 


See the sections on device drivers and Disk I/O in 
BASIC Compiler 2.00 Fundamentals for a complete 
explanation of using disk files. See also “OPEN 
‘“COM Statement”’ for information on opening 
communications files. 
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Examples: 


OPEN 
Statement 


The following examples illustrate the use of paths for 
filespec. 


Either of these statements opens the file called 
‘““~DATA” for sequential output on the default device 
in the directory called LVL2. 


19 OPEN "LVL1\LVL2\DATA" FOR OUTPUT AS #1 
or 
10 OPEN "0",#1,"LVL1\LVL2\DATA" 


Either of the next two statements opens the file 
named ““RRFILE” in the LVL1 directory on the disk 
in drive B for random input and output. The record 
length is 256. 


20 OPEN "B:LVL1\RRFILE" AS 1 LEN=256 
or 
20. OPEN: "R" Bs bVuPSRRPiLe<” 256 


Either of the following statements opens the file 
named “DATA” for sequential output on the default 
device. 


19 OPEN "DATA" FOR OUTPUT AS #1 


or 
10 OPEN "0O",#1,"DATA" 


277 


OPEN 


Statement 
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In the preceding example, note that opening for 
output destroys any existing data in the file. If you 

do not wish to destroy data, you must open for ‘y 
APPEND. 


Either of the following two statements opens the file 
named ‘“‘SSFILE”’ on the disk in drive B for random 
input and output. The record length is 256. 


10 OPEN "B:SSFILE” AS 1 LEN=256 
8 
a OPEN en i BISSFILE” 256 


This example opens the file “‘DATA.ART" on the 
disk in drive A and positions the file pointers so that 
any output to the file is placed at the end of existing 
data in the file. 


10 FILE$ = "A:DATA.ART" 
20 OPEN FILE$ FOR APPEND AS 3 “ 


OPEN 
Statement 


Line 10 in the next example opens the printer in 
random mode. Because the default width is 80, the 
lines printed by lines 20 and 30 end with a carriage 
return/line feed. Line 40 changes the printer width 
to 255, so the line feed after the carriage return is 
suppressed. Therefore, the line printed by line 50 
ends only with a carriage return and not a line feed. 
This causes the line printed by line 70 to overprint 
‘*This line is underlined’’, causing the line to be 
underlined. Line 60 changes the width back to 80 so 
the underlines and following lines end with a line 
teed. 


10 OPEN "LPT1:" AS #1 

20 PRINT #1,"Printing width 8@" 

3Q@ PRINT #1,"Now change to width 255" 

4Q WIDTH #1,255 

50 PRINT #1,'This line will be underlined" 
60 WIDTH #1,80 

70 PRINT #1,. STRINGS(283;" *) 

80 PRINT #1,"Printing width 8@ with CR/LF" 


Results: 
Printing width 8@ 
Now change to width 255 


This line will be underlined 
Printing width 8@ with CR/LF 
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OPEN 
Statement 
The following example shows how LOCK and 


UNLOCK are used with a file that is opened for 
Sequential access. 


10 OPEN "DATA" FOR INPUT AS #1 
20 ' OPENS DATA AS A SEQUENTIAL FILE 
oY. GOK #141 70 2 

HO. LOCKS ENTIRE FILE 

58 UNLOCK #1,1 TO 2 

60 © UNLOCKS ENTIRE FILE 

7Q@ LOCK #1,2 

80 © ALSO LOCKS ENTIRE FILE 

99 UNLOCK #1,2 

100 © UNLOCKS ENTIRE FILE 

110 CLOSE #1 

120 END 


File access controls can be applied to files opened 

for sequential access or random access. When 3 
writing an application to be used in a networking “& 
environment, care should be taken that file access is 
properly controlled. Data loss or corruption can 

occur when file access control is not provided. 
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OPEN 
Statement 


The following example shows how LOCK and 
UNLOCK are used with a file that is opened for 
random access. 


10 OPEN "DATA2" AS #1 

20 ' OPEN DATA2 AS RANDOM ACCESS FILE 
30 LOCK #1,3 

49 ' LOCKS RECORD #3 ONLY 

50 LOCK #1,4 TO 10 

6 ' LOCKS RECORDS #4 - #19 
70 UNLOCK #1,4 TO 19 

89 ' UNLOCKS RECORDS #4 - #10 
99 UNLOCK #1,3 

100 ' UNLOCKS RECORD #3 

110 CLOSE #1 

120 END 
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OPEN COM... 


Statement 
Purpose: Opens a communications file. "y 
Versions: Cartridge Disk Advanced Compiler 


Format: 


Remarks: 
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* KK * KK * K OK 


Valid only with Asynchronous Communications 
Adapter. 


OPEN ‘“‘COMnzn:|[speed] [,[ parity] [,[data] [,[ stop] [,RS] 
[,CS[n]] [,DS[n]] [,CD[n]] [,LF] [,PE]]]]” As 
[#|filenum [LEN =number] 


n is 1 or 2, indicating the number of the 
Asynchronous Communications Adapter. ~ 


speed is an integer constant specifying the 
transmit /receive bit rate in bits per 
second (bps). Valid speeds are 75, 110, 
150, 300, 600, 1200, 1800, 2400, 4800, 
and 9600. The default is 300 bps. 


parity is a 1-character constant specifying the 
parity for transmit and receive as follows: 


S SPACE: Parity bit always 
transmitted and received as a space 
(O bit). 


OPEN COM... 
Statement 


O ODD: Odd transmit parity; odd 
receive parity checking. 


M MARK: Parity bit always 
transmitted and received as a mark 
(1 bit): 


E EVEN: Even transmit parity, 
even receive parity checking. 


N NONE: No transmit parity, no 
receive parity checking. 


The default is EVEN (BE). 


data is an integer constant indicating the 
number of transmit/receive data bits. 
Valid values are: 5, 6, 7, or 8. The 
default is 7. 


stop is an integer constant indicating the 
number of stop bits. Valid values are 1 
or 2. The default is 2 stop bits for 75 
and 110 bps; 1 stop bit for all others. If 
you use 5 for data, a 2 here means 1-1/2 
stop bits. 
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OPEN COM... 
Statement 
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filenum is an integer expression that evaluates to 
a valid file number. The number is then 
associated with the file for as long as it is ‘9 
open and is used by other 
communications I/O statements to refer 
to the file. 


number is the maximum number of bytes that can 
be read from the communications buffer 
when using GET or PUT. The default is 
128 bytes. 


OPEN ‘“‘COM.. allocates a buffer for I/O in the 

same fashion as OPEN for disk files. It supports 

RS-232 asynchronous communication with other 

computers and peripherals. 
Note: If you compile your program with the /O 
switch, you must link the IBMCOM.OBJ = 
module. 


A communications device-can be open to only one 
file number at a time. 


The RS, CS, DS, CD, LF and PE options affect the 
line signals as follows: 


RS suppresses RTS (Request To Send) 
CS[n] controls CTS (Clear To Send) 
DS[n] controls DSR (Data Set Ready) 


CD {n] controls CD (Carrier Detect) 


LF sends a line feed following each carriage - 
return 
PE enables parity checking 


OPEN COM... 
Statement 


The CD (Carrier Detect) is also known as the RLSD 
(Received Line Signal Detect). 


Note: The speed, parity, data, and stop 
parameters are positional, but RS, CS, DS, CD, 
LF, and PE are not. 


The RTS (Request To Send) line is turned on when 
you execute an OPEN “COM.. statement unless you 
include the RS option. 


The n argument in the CS, DS, and CD options 
specifies the number of milliseconds to wait for the 
signal before returning a Device timeout error. n can 
range from O to 65535. If n is omitted or is equal to 
zero, the line status is not checked. 


The defaults are CS1000, DS1000, and CD0O. If RS 
was specified, CSO is the default. 


Normally, I/O statements to a communications file 
fail if the CTS (Clear To Send) or DSR (Data Set 
Ready) signals are off. The system waits 1 second 
before returning a Device timeout. The CS and DS 
options allow you to ignore these lines or to specify 
the amount of time to wait before the timeout. 


Normally Carrier Detect (CD or RLSD) is ignored 
when an OPEN “‘COM... statement is executed. The 
CD option allows you to test this line by including 
the m parameter, in the same way as CS and DS. If n 
is omitted or is equal to zero, Carrier Detect is not 
checked at all (which is the same as omitting the CD 
option). 
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OPEN COM... 
Statement 


The LF parameter is intended for those using 
communications files to print to a serial line printer. 
When you specify LF, a line feed character (hex 0A) “as 
is automatically sent after each carriage return , 
character (hex OC). (This includes the carriage 

return sent as a result of the width setting.) INPUT 

# and LINE INPUT #, when used to read from a 
communications file that was opened with the LF 

option, stop when they see a carriage return. The 

line feed is always ignored. 


The PE option enables parity checking. The default 
is no parity checking. The PE option causes a Device 
I/O error on parity errors and turns on the 
high-order bit for 7 or fewer data bits. The PE 
option does not affect framing and overrun errors. 
These errors always turn on the high-order bit and 
cause a Device I/O error. 


Any coding errors within the string expression “A 
starting with speed result in a Bad file name error. No 
indication is given as to which parameter is in error. 


See also ‘‘Communications,” in BASIC Compiler 
2.00 Fundamentals for more information on control 
of output signals and other communications support. 


If you specify 8 data bits, you must specify parity N. 
BASIC uses all 8 bits in a byte to store numbers, so 
if you are transmitting or receiving numeric data (for 
example, by using PUT), you must specify 8 data 
bits. (This is not necessary if you are sending 
numeric data as fext.) 


See also the previous entry, ““OPEN Statement,” for 
information on opening devices other than 
communications devices. 
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Examples: 


OPEN COM... 
Statement 


In this example, file 1 is opened for communication 
with all defaults. The speed is 300 bps with even 
parity. There are 7 data bits and 1 stop bit. 


10 OPEN "COM1:" AS #1 


In this example, file 2 is opened for asynchronous 
I/O at 1200 bps; no parity is to be produced or 
checked; 8-bit bytes are sent and received; and 1 
stop bit is transmitted. 


10 OPEN "COM2:1200,N,8" AS #1 


This example opens COM1: at 9600 bps with no 
parity and 8 data bits. CTS, DSR, and CD are not 
checked. 


19 OPEN "COM1:9600,N,8,,CS,DS,CD" AS #1 


This example opens COM1: at 1200 bps with the 
defaults of even parity, 7 data bits, and 1 stop bit. 
RTS is sent, CTS is not checked, and Device timeout 
is given if DSR is not seen within 2 seconds. The 
commas are required to indicate the position of the 
parity, start, and stop parameters, even though a value 
is not specified. 


10 OPEN "COM1:1200,,,,CS,DS2000" AS #1 


An OPEN ‘‘COM statement can be used with an 
ON ERROR statement to make sure a modem is 
working properly before sending any data. 
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OPEN COM... 
Statement 


For example, the following program makes sure you 
get Carrier Detect (CD or RLSD) from the modem 
before starting. Line 20 is set to timeout after 10 
seconds. TRIES is set to 6 so we give up if Carrier 
Detect is not seen within 1 minute. Once 
communication is established, the file reopens with a 
shorter delay until timeout. 


10 TRIES=6:0N ERROR GOTO 100 

20 OPEN "COM1:300,N,8,2,CS,DS,CD10@00" AS #1 
3@ ON ERROR GOTO @ 

40 CLOSE #1 ‘Works so can continue 

50 GOTO 1000 


100 TRIES=TRIES-1 
119 IF TRIES=0 THEN ON ERROR GOTO @ ‘give up 
120 RESUME 


1000 OPEN "COM1:300,N,8,2,CS,DS,CD200@" AS #1 


The next example shows a typical way to use a 
communication file to control a serial line printer. 
The LF parameter in the OPEN ‘“‘COM statement 
ensures that lines do not print on top of each other. 


10 WIDTH "COM1:", 132 
20 OPEN °"COM1:1200,N,8, ,CS19000, 
DS19009,CD19000,LF" AS #1 
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wy Purpose: 


Versions: 


Format: 


Remarks: 


OPTION BASE 
Statement 


Declares the minimum value for array subscripts. 


Cartridge Disk Advanced Compiler 


* KK * KK * KOK * KOK 


OPTION BASE n 


n is 1or 0. 


The OPTION BASE statement must be coded before 
you define or use any arrays. An error occurs if you 
change the base value when arrays exist. The default 
base is O. If the statement: 


OPTION BASE 1 


is executed, the lowest value an array subscript can 
have is 1. 


Note: You must compile with the /D parameter 
to enable the compiler to check array bounds. 
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OUT 


Statement 
Purpose: Sends a byte to a machine output port. 
Versions: Cartridge Disk Advanced Compiler 
* KK * * K * kK 
Format: OUT n,m 
Remarks: 
n is a numeric expression for the port number, 
in the range O to 65535. 
m is a numeric expression for the data to be 
transmitted, in the range O to 255. 
See also the IBM Personal Computer Technical 
Reference manual for a description of valid port 
numbers (I/O addresses). 
OUT is the complementary statement to the INP 
function. See also “INP Function.” 
Example: 
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The following example turns the speaker on and off. 


100 A=INP(&H61) 

110 OUT &H61, A OR 3 : REM Speaker on 

120 WHILE INKEY$="" : WEND 

13Q@ OUT &H61, A AND NOT 3 : REM Speaker off 
149 END 


PAINT 
Statement 


oe Purpose: _ Fills in an area on the screen with the selected color. 


Versions: Cartridge Disk Advanced Compiler 
* ok * KK * KK 


Graphics mode only. 
Format: PAINT (x,y) [,[paint] [,[ boundary] [,[background]]|]] 
Remarks: 


(x,y) are the coordinates of a point within the 
area to be filled in. The coordinates can 
be given in absolute or relative form. 
For more information on specifying 
coordinates, see ‘““Graphics Modes’’ 
under “Input and Output” in BASIC 
Compiler 2.00 Fundamentals. This point 
is used as a Starting point. Points 
specified outside the limits of the screen 
are not plotted, and no error occurs. 


Paint can be a numeric or string expression. 
It is used to fill a color or pattern in or 
around a bounded area. When paint is a 
numeric expression, it chooses an 
attribute from the legal attribute range 
for the current screen mode. 


In SCREEN 1, (medium resolution), 
attribute can range from O to 3. In 
SCREEN 2, (high resolution), attribute 


YY can be O or 1. 
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PAINT 
Statement 
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The default color attribute for the 
foreground is the maxiumum color 
attribute for that screen mode. 


The default color attribute for the 
background is always zero. 


PAINT 
Statement 


boundary _ is an integer expression in the legal 
attribute range of the current screen 
mode. It defines the attribute for the 
edges of the figure to be painted. 


background 
is a 1-byte string expression used in 
paint tiling. 


In medium resolution, you can fill inside or around a 
defined area with any one of four colors from the 
current palette defined by the COLOR statement. 
Examples of this are filling a red circle with green, or 
surrounding a red circle with green. 


paint begins at the specified starting point and covers 
an area until it meets the specified boundary 
attribute. Therefore, paint must always begin inside 
the area to be painted. If the specified starting point 
already has the same attribute as boundary, painting 
stops at that point and appears not to occur. An 
example of this is plotting a point with PSET that has 
the same attribute as boundary, and using the 
coordinates of that point with the PAINT statement. 
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PAINT 
Statement 


PAINT fills any designated area nc matter what the 
shape of the area; however, the more complex the 

edges of a figure (jagged edges, for instance), the ‘> 
more stack space BASIC uses. Under these 
circumstances you may want to use the CLEAR 
statement at the beginning of your program to 
increase the stack space. 


The PAINT statement allows scenes to be displayed 
with very few statements. 


In the example that follows, the PAINT statement in 
line 30 fills in the box drawn in line 20 with the 
color represented by the attribute in the current 
palette. 


10 SCREEN 1 
20 LINE (@,0)-(190,150) ,2,B 
30 PAINT (50,50) ,1,2 


The following discussion deals with paint tiling only. 


To use paint tiling, the paint attribute must be a 
string expression in the form: 


CHR$(&Hnn)+CHR$(&Hnn)+CHR$(&Hnn) +... 


The CHR$ sequence specifies a bit mask that is 1 
byte wide. When the mask is plotted all the way 
across and down the designated area defined by 
boundary, a pattern is created rather than a solid 
color. You design the pattern. The two hexadecimal 
digits in the CHR$ expression correspond to 8 bits, 
or 1 byte. The string expression can contain up to 64 
bytes. 
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PAINT 
Statement 


The design created by the string expression can be 
mapped as follows: 


x increases --> 


76543219 
0,0 XKXXE ee Tile byte O 
O.1 XXKXEROo Tile byte 1 
Q,2 XXXXRaoe Tile byte 2 
0,63 XX XX See Tile byte 63 


(maximum allowed) 


The tile pattern is repeated uniformly over the area 
defined by boundary. If you do not define an area 
with boundary, the whole screen is your designated 
area. Each byte of the tile string masks 8 bits along 
the x axis when plotting points. Each byte of the tile 
string is rotated as required to align the pattern along 
the y axis. BASIC chooses the particular byte of the 
pattern to plot, using the formula y mod tile length. 


The method of designing patterns in each screen 
varies depending on the number of color attributes 
available in each screen mode. This is so because the 
number of bits per pixel is directly related to the 
number of color attributes available in each screen 
mode. In any screen, where X is the total number of 
color attributes for that screen: 


where Y is the number of bits per pixel. In high 
resolution, each byte of the string is able to plot 8 


points across the screen (1 bit per pixel), since 
LOG,(2)=1. 
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PAINT 
Statement 


In SCREEN 1, one medium-resolution tile byte 
describes 4 pixels, since medium resolution has only 
2 bits per pixel: that is, LOG,(4)=2 bits per pixel. ‘> 
Every 2 bits of the tile byte describes 1 of 4 possible 

color attributes associated with each of the 4 pixels 

to be plotted. 


Bits per Pixel 
SCREEN 1 


SCREEN 2 


Because there is only 1 bit per pixel in high 
resolution, a point is plotted at every position in the 
bit mask that has a value of 1. In high resolution, the 
screen can be painted with x’s using the following 
example: 


5 REM Without background tile 
£0 Cis SCREEN <1: “COLOR. REY OFF 
20 LOCATE 12,7:PRINT "I LOVE MY IBM COMPUTER™ 
3Q PAINT(32@0,100) ,CHR$(&H81)+CHR$(&H42 )+ 
CHR$( &H24 )+CHR$ (&H18 )+CHR$ ( &H18) + 
CHR$( &H24 )+CHR$ ( &H42 )+CHR$ ( &H81 ) 


The length of this mask is 8, indexed 0 through 7. 

In this case, PAINT at coordinates (320,100) begins a 
by plotting byte 4. This is calculated using the y mod 

tile length formula by substituting 100 for y and 8 for 

tile length. 
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PAINT 


Statement 


This pattern appears on the screen as: 


Tile byte O 
Tile byte 1 
Tie byte 2 
Tile byte 3 
Tile byte 4 
Tile byte 5 
Tile byte 6 
Tile byte 7 


x increases --> 
1OoO000001 
01000010 
00100100 
00011000 
00011000 
00100100 
01000010 
10000001 


CHR$(&H81) 
CHR$(&H42) 
CHR$(&H24) 
CHR$(&H18) 
CHR$(&H18) 
CHR$(&H24) 
CHR$(&H42) 
CHR$(&H81) 


The following chart shows the binary and 
hexadecimal values associated with each attribute in 
medium resolution. 


Pattern to 
draw solid 


Pattern to 


Color Attrib. 
i draw solid 


palette 0 


line in line in 
binary 


hexadecimal 


01010101 
10101010 
11111111 


Attrib. Pattern to Pattern to 
palette 1 | in draw solid draw solid 
binary line in line in 
binary hexadecimal 


cyan O1 01010101 &HS55 
magenta 10101010 | &HAA 
white FF P44-9327 1 &HFF 
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PAINT 
Statement 
In medium resolution, the following example plots a 


pattern of boxes with a border color of red in palette 
0 and magenta in palette 1. 


iy Cia: SURECH 1: COLOR 1 REY OFe 
20 LOCATE 12,7:PRINT "I LOVE MY IBM COMPUTER" 
30 PAINT (320,100) ,CHR$(&HAA)+CHR$(&H82 )+ 
CHR$( &H82)+CHR$ ( &H82 ) +CHR$ ( &H82 ) + 
CHR$( &H82 )+CHR$ ( &H82 )+CHR$ ( &HAA ) 


76543210 
Tile byte 0 TU LOLOL CHR$(&HAA) 
Tile byte 1 10000010 CHR$(&H82) 
Tile byte 2 10000010 CHR$(&H82) 
Tile byte 3 10000010 CHR$(&H82) 
Tile byte 4 10000010 CHR$(&H82) 
Tile byte 5 10000010 CHR$(&H82) 
Tile byte 6 tHOO00TO CHR$(&H82) 
ae bye 7 10101010 


CHR$(&HAA) “~ 


Occasionally, you may want to tile over an already : 
painted area that is the same color or pattern as two 
consecutive bytes in the tile mask. Normally, this 
constitutes a terminating condition because your 

point is bounded by points of the same bit pattern. 

(An example follows on the use of background.) 


You can use the background attribute to skip this 
terminating condition. You cannot specify more 
than two consecutive lines in the tile pattern that 
matches this background attribute. Doing so causes 
an Illegal function call error. 
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PAINT 
Statement 


Examples: The program below demonstrates how to tile an area 
with three lines of red, two lines of green, and one 
YY line of red. The palette then changes to show that 
the same tile mask yields the same pattern with 
different colors. 


10 CLS: SCREEN. 1, @24ey-OFF 

20 TIL$=CHR$(&HAA)+CHR$( &HAA)+CHR$ ( &HAA ) 
+CHR$(&H55 )+CHR$(&H55 )+CHR$ ( &HFF ) 

38 COLOR 9,0 ‘choose palette Q@ 

59 GOSUB 1000 

68 COLOR @,1 ‘choose palette 1 

78 GOTO 1920 

1000 PAINT (125,50) ,TIL$,2 

1010 RETURN 


The following example uses paint tiling with the 
background attribute. 


10° CLES: SCREEN 1: COLQ@RS@. 4 REY. OFF 

20 TIL$=CHR$(&H5F )+CHR$(&H5F )+CHR$ ( &H27 )+CHR$ ( &H81 ) 
30 VIEW (1,1)-(158,100) ,0,2 

40 LOCATE 3,22:PRINT "<---Without back-" 

50 LOCATE 4,22:PRINT “ ground tile " 

60 PAINT (125,50) ,CHR$(&H5F ) 

70 PAINT (125,50) ,TIL$,2 


99 ‘with background tile’ 

100 ' 

110 VIEW (160,190)-(319,198) ,@,2 

12@ LOCATE 16,1:PRINT "With background-->" 
13@ LOCATE 17,1:PRINT “tile chr$(&H5F)" 
140 PAINT (125,50) ,CHR$(&H5F ) 

15@ PAINT (125,50) ,TIL$,2,CHR$(&H5F ) 

16Q@ LINE (1,100)-(319,19@0) ,3 

170 FOR I=1 TO 250@:NEXT I 


Purpose: Allows control of the hardware palette. ’y 


Versions: Cartridge Disk Advanced Compiler 
* KOK * OK 


Format: PALETTE [attribute][, color] 
Remarks: 


attribute is an expression that evaluates to an 
integer value in the range of 0 to 15 that 
indicates the attribute which is to be 
changed. 


color is an expression that evaluates to an 
integer value that is a color in the range 
of O to 15 to be assigned to attribute. “» 


The PALETTE statement without any arguments 
can be used to reset all palettes to their default 
values. 


The PALETTE statement can also be used to change 
the color of text. PALETTE used in conjunction 
with the COLOR statement allows as much 
flexibility with text in graphics mode as in text mode. 


PALETTE, used with SCREEN and CLEAR, can be 
a useful animation tool. PALETTE can be used to 
give the effect of making images disappear and 
reappear quickly. You can draw an object in a given 
color and use the PALETTE statement to change the 
object to the background color making the object 
seem to disappear. 
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Examples: 


When you want to assign colors to many attributes 
quickly you should use the PALETTE USING 
statement. See the “PALETTE USING” statement 
for more information. 


The PALETTE statement allows you to change the 
color of any object or text on the screen. For 
example, the following statement draws a blue line. 


The PALETTE statement can be used to change the 
color of the line. 


PALETTE-+ 5 


This statement says that every time you use 
attribute 1 to describe the color of an image, you see 
the color 3 (cyan). From this point on when you 
reference the color attribute 1, you actually see the 
color cyan. 


Purpose: Allows the setting of all palette entries with one ‘> 
statement. 


Versions: Cartridge Disk Advanced Compiler 
** KK ** KK 


Format: PALETTE USING [arrayname(starting) | 
Remarks: 


array name is an integer array that must have 16 
elements indexed from the starting 
index. 


starting is an integer indicating the starting 


position in the array for assigning the 
palette colors. 


PALETTE USING allows you to quickly assign the 
colors for many attributes simultaneously. Any entry 
in the array with a value of -1 does not modify the 
current color for that attribute. PALETTE USING 
is valid for both text and graphic modes. 


Example: 


In the following example, the attributes of 0,1,2, and 
3 have been reassigned colors 14,4,5 and 6 
respectively. The rest of the colors remain 
unchanged. Statement 200 changes the colors on the 
screen from black, blue, green, and cyan to yellow, 
red, magenta, and brown. Attribute 1 now 
corresponds to color 14; attribute 2 now corresponds 
to red, and so on. 


The 


10@ 
110 
120 
139 
149 
159 
169 
179 
180 
199 
200 
219 
220 
230 
240 


accompanying chart illustrates these changes. 


DEFINT A-Z 

SCREEN’ T:CES 

LINE (50,50)-(120,120) ,1,BF 

LINE (60,60)-(110,11@) ,2,BF 

LINE (70,70)-(100,190) ,3,BF 

DIM PAL (16) 
5 


DATA 14,4,5,6,<1.-1,-1,-1 

DATA: .- 1, ~ Tbe eee 1. 1 

FOR I = @ TO 15 

READ PAL(I) 

NEXT I 

FOR T=1 TO 10Q0@00:NEXT T ‘delay loop 
PALETTE USING PAL(Q@) ‘change colors 
END 
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Ou. i Bck eee 
ee ee 
62 | Brown ee 
Bo Gry 
9 | Light Blue___| -1-Unchanged 


oe Purpose: 


Versions: 


Format: 


Remarks: 


Example: 


Allows copying from one screen page to another in 
all screen modes. 


Cartridge Disk Advanced Compiler 


2k ok * 7 


PCOPY source page , destination page 


source page is an integer expression in the 
range of the number of pages, 
that is determined by the current 
video memory size and the size 
per page for the current screen 
mode. 


destination page The destination page has the 
Same requirements as the source 


page. 
PCOPY defaults to O for the active page. 


For more information on pages and memory 
allocation, refer to the CLEAR statement, the 
SCREEN statement, and the section ‘‘Graphics 
modes” in BASIC Compiler 2.00 Fundamentals. 


The following example copies the contents of page 1 
to page 2. 


Pog). bie 


PEEK 
Function 


Purpose: Returns the byte read from the indicated memory 
position. 


Versions: Cartridge Disk Advanced Compiler 
** ok 2 ok * ok * ok 


Format: v = PEEK(n) 
Remarks: 


n is a Single-precision value in the range 0 to 
1048575 This is the offset from the current 
segment as defined by the DEF SEG 
statement. See ‘““DEF SEG Statement.”’ 


The returned value is an integer in the range 0 to 
235. 


PEEK is the complementary function to the POKE 
statement. Because the allocation of memory is 
different, PEEKs and POKEs designed for the 
interpreter do not work with the compiler. See 
‘““POKE Statement.”’ 


306 


PEEK 
Function 


Example: The following example in a program tests which 
display adapter is on the system. After line 30 is 
executed, the variable IBMMONDO has a value of O 
if the IBM Color/Graphics Monitor Adapter is used, 
or 1 if the IBM Monochrome Display and Printer 
Adapter is used. 


19 ‘test display adapter 

20 DEF SEG=@ 

30 IF (PEEK(&H41@) AND &H3@)=&H3@ THEN IBMMONO=1 _ 
ELSE IBMMONO=@ 
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PEN 
Statement and Function 


Purpose: — Reads the light pen. ‘> 
Versions: Cartridge Disk Advanced Compiler 
* KK * KK ** OK ** kK 


Format: As a statement: 
PEN ON 
PEN OFF 


PEN STOP 


As a function: 


vy = PEN(n) “& 


Remarks: The PEN function, v=PEN(n), reads the light pen 
coordinates. 


n is a numeric expression in the range 0 to 9 and 
affects the value returned by the function as 
follows: 


p A flag indicating if pen was down since 
last poll. Returns -1 if down, O if not. 


1 Returns the x coordinate where pen 
was last activated. 


Range is 0 to 319 in medium -_ 
resolution, and O to 639 in high 
resolution. 
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PEN 
Statement and Function 


Returns the y coordinate where pen 
was last activated. Range is 0 to 199. 


Returns the current pen switch value. 
-1 if down, O if up. 


Returns the last known valid x 
coordinate. 


Range is O to 319 in medium 
resolution, and O to 639 in high 
resolution. 


Returns the last known valid y 
coordinate. Range is 0 to 199. 


Returns the character row position 
where pen was last activated. Range is 
1 to 24. 


Returns the character column position 
where pen was last activated. Range is 
1 to 40 or 1 to 80, depending on 
WIDTH. 


Returns the last known valid character 
row. Range is 1 to 24. 
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PEN 
Statement and Function 


9 Returns the last known valid character 


column position. Range is 1 to 40 or 1 
to 80, depending on WIDTH. “a 


PEN ON enables the PEN read function. The PEN 
function is initially off. A PEN ON statement must 
be executed before any pen read function calls can 

be made. A call to the PEN function while the PEN 
function is off results in an Illegal function call error. 


To improve execution speed, turn the pen off with a 
PEN OFF statement when you are not using the light 
pen. 


place with the ON PEN statement. After PEN ON, 
if a nonzero line number was specified in the ON 
PEN statement, every time the program starts a new 
statement or line number, (depending on whether 
you compiled using /V or /W), BASIC checks to see 
if the pen was activated. See ““ON PEN Statement.” 


Executing PEN ON also allows trapping to take “~ 


PEN OFF disables the PEN read function. No 
trapping of the pen takes place. Action by the light 
pen is not remembered even if it does take place. 


PEN STOP disables trapping of light pen activity. If 
activity does occur, however, it is remembered, so an 
immediate trap occurs when a PEN ON is executed. 


When the pen is down in the border area of the 
screen, the values returned are inaccurate. A“ 
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Example: 


PEN 
Statement and Function 


This example prints the pen value since the last poll, 
and the current value. 


19 PEN ON 

20 FOR I=1 TO 500 

30 X=PEN(@): X1=PEN(3) 
40 PRINT X, X1 

99 NEXT 

600 PEN OFF 
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PLAY 
Statement 


Purpose: Plays music as specified by string. ‘eo 


Versions: Cartridge Disk Advanced Compiler 


Format: PLAY string 


Remarks: PLAY implements a concept similar to DRAW by 
imbedding a “‘tune definition language”’ into a 
character string. 


Note: In a compiled program, if the program 
ends before the buffer is empty, the music stops 
playing. This is different from the interpreter. 
If your program is sensitive to this, you can 
place a dummy FOR..NEXT loop prior to 
exiting your program. 


string is a string expression consisting of 
single-character or double-character music 
commands. 
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PLAY 
Statement 


The commands in PLAY are: 


A to G with optional #, +, or - 


On 


Plays the indicated note in the current octave. 
A number sign (#) or plus sign (+) afterward 
indicates a sharp; a minus sign (-) indicates a 
flat. A #, +, or - is not allowed unless it 
corresponds to a black key on a piano. For 
example, B# is an invalid note. 


Octave. Sets the current octave for the notes 
that follow. There are seven octaves, 
numbered 0 to 6. Each octave goes from C to 
B. Octave 2 starts with middle C. Octave 4 
is the default octave. 


Go up to the next higher octave and play note 
n. Each time note n is played, the octave goes 
up, until it reaches octave 6. For example, 
PLAY ‘‘>A”’ raises the octave and plays note 
A. Each time PLAY ‘“‘>A”’ is executed, the 
octave goes up until it reaches octave 6; then 
each time PLAY “‘>A” executes, note A 
plays at octave 6. 


Go down one octave and play note n. Each 
time note n is played, the octave goes down, 
until it reaches octave O. For example, PLAY 
‘“<A’”’ lowers the octave and plays note A. 
Each time PLAY “‘<A’”’ is executed, the 
octave goes down until it reaches octave 0; 
then each time PLAY ‘“‘<A”’ executes, note A 
plays at octave 0. 


Plays note n, which can range from 0 to 84. 

In the 7 possible octaves, there are 84 notes. 
nQ means “rest.’’ This is an alternative way of 
selecting notes beside specifying the octave 
(O n) and the note name (A-G). 
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PLAY 
Statement 


Ln __ Sets the length of the notes that follow. The 
actual length of the note is 1/n. n can range 
from | to 64. ” 


Length Equivalent 


L1 whole note 

L2 half note 

L3 one of a triplet of three half notes 
(1/3 of a four-beat measure) 

L4 quarter note 

L5 one of a quintuplet 
(1/5 of a measure) 

L6 one of a quarter-note triplet 


L64  sixty-fourth note 


The length can also follow the note when you 
want to change only the length of the note. 
For example, A16 is equivalent to LI6A. 


Pn Pause (rest). m can range from 1 to 64, and 
figures the length of the pause in the same 
way as L (length). 


(dot or period) When placed after a note, 
causes the note to be played as a dotted note. 
A dot increases the duration of a note by half 
the duration of the note. A note can have 
more than one dot. Each dot increases the 
total value of the note by 1/2 the value of the 
previous dot. For example, a double-dotted 
halfnote is equivalent in duration to a half 
note plus a quarter note plus an eighth note. 
Dots can also appear after a pause (P) to 
scale the pause length in the same way. 
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MF 


MB 


MN 


ML 


MS 


PLAY 
Statement 


Tempo. Sets the number of quarter notes ina 
minute. m can range from 32 to 255. The 
default is 120. Under ““SOUND Statement”’ is 
a table listing common tempos and the 
equivalent beats per minute. 


Music foreground. Music (created by 
SOUND or PLAY) runs in foreground. Each 
subsequent note or sound does not start until 
the previous note or sound is finished. You 
can press Ctrl-Break to exit PLAY. Music 
foreground is the default state. 


Music background. Music (created by 
SOUND or PLAY) runs in background 
instead of in foreground. Each note or sound 
is placed in a buffer, allowing the BASIC 
program to continue executing while music 
plays in the background. The music 
background buffer can hold up to 32 notes at 
one time. 


Music normal. Each note plays 7/8 of the 
time specified by L (length). This is the 
default setting of MN, ML, and MS. 


Music legato. Each note plays the full period 
set by L (length). 


Music staccato. Each note plays 3/4 of the 
time specified by L. 


X variable; 


Executes specified string. 
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PLAY 
Statement 


In all these commands, the n argument can be a 
constant such as 12, or it can be 


VARPTRS$(variable); where variable is the name of a 
variable. Any blanks in string are ignored. 


The VARPTR$ form is the only one that can be used 
in compiled programs. For example: 


Interpreter Method Compiler Method 

PLAY = 2AS =" PLAY "X"+VARPTR$(A$) 
PEAY e021 ¢" PLAY "O="+VARPTR$(1I) 
You can use X to store a “‘subtune”’ in one string 


and call it repetitively with different tempos or 
octaves from another string. 


There are two ways you can specify variables in a 
PLAY or DRAW string for the compiler: 


e Use the ‘‘X”’ variable form, concatenated (‘‘+’’) 
with the VARPTRS$ of the variable itself. 


e« Use the DRAW or PLAY macro, followed by an 
equal sign (=) and concatenated (‘‘+’’) with the 
VARPTRS$ of the variable itself. 


The following examples demonstrate both 
methods. 
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Examples: 


PLAY 
Statement 


The following example plays a tune. 


10 
20 


‘little lamb 
MARY $="GFE-FGGG" 


30 PLAY "MB T10@ 03 L8,X"+VARPTR$(MARY$) ,"P8 
FFF4" 


49 


PLAY "GB-B-4, X"+VARPTR$(MARY$)+ "GFFGFE-." 


The following example plays the scale from octave 0 
to octave 6. 


90 


Play the scale using > octave 
SCALE$="CDEFGAB" 

PLAY "O@ X"+VARPTR$(SCALE$) 

FOR I=1 TO 6 

PLAY ">X"+VARPTR$(SCALE$) 

NEXT 

' Play the scale using < octave 
PLAY "06 X"+VARPTR$(SCALE$) 

FOR I=1 TO 6 


100 PLAY "<X"+VARPTR$(SCALE$) 
11Q@ NEXT 
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PLAY 
Statement 


PLAY(n) 
Function 


Purpose: Returns the number of notes currently in the music 
background buffer. 


Versions: Cartridge ~Disk Advanced Compiler 


Format: v=PLAY(n) 
Remarks: 


n is a dummy argument that can have any value. 


PLAY (n) returns a O when the program is running in 
Music Foreground mode. The maximum value that 
can be returned is 32, which is the maximum number 
of notes held in the buffer. 
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PLAY(n) 
Function 


PLAY (n) returns notes in the buffer only when you 
are using Music Background (MB) mode. 


Example: The following example begins playing a new tune y 


when there are 5 notes left in the background music 
buffer. 


10 ‘When 5 notes in background buffer 

20 ‘go to line 1900 and play another tune 
30 PLAY "MB CDEFGAB" 

40 IF PLAY(1)=5 GOTO 1000 

50 GOTO 2000 


1000 PLAY "MB @4 7200 L4 MS GG#GE" 
2000 END 
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PMAP 
Function 


oe Purpose: Maps physical coordinates to world coordinates or 
world coordinates to physical coordinates. 


Versions: Cartridge Disk Advanced Compiler 
* 6 * KK KK 


Graphics mode only 


Format: v=PMAP(x,n) 


Remarks: 
x coordinate of the point that is to be 
mapped 
n can be a value in the range O to 3 such 
that: 
0 maps the world coordinate x to 
the physical coordinate x 
1 maps the world coordinate y to 
the physical coordinate y 
Zz maps the physical coordinate x to 
the world coordinate x 
3 maps the physical coordinate y to 
the world coordinate y 
PMAP is used to translate coordinates between the 
world system as defined by the WINDOW statement 
VY and the physical coordinate system. 
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PMAP 


Function 
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PMAP(x,0) and PMAP(x,1) are used to map values 
from the world coordinate system to the physical 
coordinate system. “a 


PMAP(x,2) and PMAP(x,3) are used to map values 
from the physical coordinate system to the world 
coordinate system. 


For example, if the statement 
SCREEN 1: WINDOW (-1.,-1)-(1439 


is in effect you can use PMAP to map the world 
coordinate points of (-1,-1) and (1,1) to their 
corresponding physical points on the screen. 


PMAP(-1,0) returns the physical x coordinate value 
of O. 


PMAP(-1,1) returns the physical y coordinate value “ 
of 199. 


PMAP(1,0) returns the physical x coordinate value 
of 319: 


PMAP(1,1) returns the physical y coordinate value 
of O. 


The above information tells you that the point 
(-1,-1), which is in the lower left corner of the 
screen, corresponds to the physical point (0,199). 
You also know that the point (1,1), which is in the 
upper right corner, corresponds to the physical point 
(319-0). 


ww Purpose: 


Versions: 


Format: 


Remarks: 


POINT 
Function 


The first form returns the color attribute of the 
specified point on the screen. The second form 
returns the value of the current x or y graphics 

coordinate. 


Cartridge Disk Advanced Compiler 


* ok ok * Kk ok 


Graphics mode only. 
y= POINT (ay) 


v = POINT (n) 


(x,y) are the coordinates of the point to be 
used. They must be in absolute form as 
explained in “‘Specifying Coordinates’”’ 
under “‘Graphics Modes” in BASIC 
Compiler 2.00 Fundamentals. 


If the point given is out of range, the value 
-] is returned. 


In medium resolution valid returns are O, 


1, 2, and 3. In high resolution they are 0 
and 1. 
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POINT 
Function 


n returns the value of the current x or y 


graphics coordinate. n can have a value 
from 0 to 3 where: 


0 returns the current physical x 
coordinate. 

1 returns the current physical y 
coordinate. 

p returns the current world x 


coordinate if WINDOW is 
active. If WINDOW is not 
active, returns the current 
physical x coordinate. 


> returns the current world y 
coordinate if WINDOW is 


active. If WINDOW is not 
active, returns the current 
physical y. 


See also ‘““WINDOW Statement.”’ 
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Examples: 


POINT 
Function 


The following example inverts the current setting of 
point (1,I). 


19 SCREEN 2 
20 IF POINT(1,1}e39 SHEN PRESET(1I,1) 
ELSE PSET(I,1) 
Or 
20 PSET(I,1),1-POENRI TT) 


This example illustrates values returned by the 
POINT function. Note the change in the values 
depending upon WINDOW. 


CLS: SCREEN 1 ,@:REy Fee DeEFINT A-Z 

PRINT "POINT(n) with WINDOW inactive" 

GOSUB 119 

WINDOW (@,0)-(319,199) 

PRINT "“POINT(n) with WINDOW active" 

GOSUB 11@ 

PRINT "POINT(n) with WINDOW and SCREEN active" 
WINDOW SCREEN (@,0)-(319,199) 

GOSUB 11@ 


100 END 

£19: PSET (5515) 

128 FOR I=@ TO 3 

130 PRINT INT(POINT (1)); 
140 NEXT 

150 PRINT:PRINT 

16% RETURN 


Results 


POINT(n) with WINDOW inactive 

See TBs ee 

POINT(n) with WINDOW active 

a ee OS eS 

POINT(n) with WINDOW and SCREEN active 
>» 15 5. 15 
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POKE 


Statement 
Purpose: Writes a byte into a memory location. “yy 
Versions: Cartridge Disk Advanced Compiler 


Format: 


Remarks: 
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* KOK * KK ** KOK * 


POKE n,m 


n is a Single-precision value in the range O to 
1048575. It indicates the offset into the 
current segment where that data is to be 
written. The current segment is defined by 
the DEF SEG statement. See ““DEF SEG 
Statement.”’ 


m m is the data to be written to the specified “ 
location. It must be in the range O to 255. 


The complementary function to POKE is PEEK. 
POKE and PEEK are useful for efficient data 
storage and loading assembly language subprograms. 
See also “‘Peek Function.”’ 


Warning: BASIC does not check the offset 
specified; therefore, do not go POKEing around 
in BASIC’s stack, BASIC’s variable area, or your 
BASIC program. 


Because the allocation of memory is different, 
PEEKs and POKEs designed for the interpreter do 
not work with the compiler. 


POKE 
Statement 


Example: See “Calling Assembly Language Subprograms” in 
Y BASIC Compiler 2.00 Fundamentals. 
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POS 
Function 


Purpose: Returns the current cursor column position. 


Versions: Cartridge Disk Advanced Compiler 
** KK * KK * KK ** KK 


Format: v = POS(n) 
Remarks: 7 is a dummy argument. 


The current horizontal (column) position of the 
cursor is returned. The returned value is in the range 
1 to 40 or 1 to 80, depending on the current WIDTH 
setting. 


CSRLIN can be used to find the vertical (row) 
position of the cursor. See ““CSRLIN Variable.”’ 


See also ‘“‘LPOS Function.”’ 


Example: This example prints a carriage return (moves the 
cursor to the beginning of the next line) if the cursor 
is beyond position 60 on the screen. 


IF POS(@)>6@ THEN PRINT CHR$(13) 
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vv Purpose: 


Versions: 


Format: 


Remarks: 


PRINT 
Statement 


Displays data on the screen. 


Cartridge Disk Advanced Compiler 


* OK * * KK * KK 


PRINT [list of expressions] [;|, | 


list of expressions 
is a list of numeric and/or string 
expressions, separated by commas, blanks, 
or semicolons. Any string constants in the 
list must be enclosed in quotation marks. 


If the list of expressions is omitted, a blank line is 
displayed. If the list of expressions is included, the 
values of the expressions are displayed on the screen. 


Print Positions 


The position of each printed item is determined by 
the punctuation used to separate the items in the list. 
BASIC divides the line into print zones of 14 spaces 
each. 


In the list of expressions: 
e Typing a comma between expressions causes the 


next value to be printed at the beginning of the 
next zone. 


e Typing a semicolon causes the next value to be 
printed immediately after the last value. 


PRINT 
Statement 


e Typing one or more spaces between expressions 
has the same effect as typing a semicolon. 


If a comma, semicolon, or SPC or TAB function > 
ends the list of expressions, the next PRINT 

statement begins printing on the same line, spacing 
accordingly. If the list of expressions ends without a 
comma, semicolon, SPC or TAB function, a carriage 

return is printed at the end of the line; that is,. 

BASIC moves the cursor to the beginning of the next 

line. 


If the length of the value to be printed exceeds the 

number of character positions remaining on the 

current line, the value is printed at the beginning of 

the next line. If the value to be printed is longer than 

the defined WIDTH, BASIC prints as much as it can 

on the current line and continues printing the rest of 

the value on the next physical line. “A 


Scrolling occurs as described under ‘“Text Mode”’ in 
BASIC Compiler 2.00 Fundamentals. 


Printed numbers are always followed by a space. 
Positive numbers are preceded by a space. Negative 
numbers are preceded by a minus sign. When 
single-precision numbers can be represented with 
seven or fewer digits in fixed-point format as 
accurately as in floating-point format, they are 
returned in fixed-point or integer format. For 
example, 104(-7) is printed as .OOOOO01 and 
10A4(-8) is output as 1E-8. 


BASIC automatically inserts a carriage return/line 
feed after printing width characters, where width is 40 

or 80, as defined by the WIDTH statement. This = 
causes two lines to be skipped when you print 
exactly 40 (or 80) characters, unless the PRINT 
statement ends in a semicolon (;). 
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Examples: 


PRINT 
Statement 


LPRINT is used to print information on the printer. 
See ‘““LPRINT and LPRINT USING Statements.” 


In this example, the commas in the PRINT statement 
cause each value to be printed at the beginning of the 
next print zone. 


19 X=5 
20° PRINT -X+5 9 Reeds (=o) 


Results: 
1Q Q =25 
Here, the semicolon at the end of line 20 causes 
both PRINT statements to be printed on the same 
line. 
1@ INPUT X 
20 PRINT X;"SQUARED IS";XA2;"AND"; 
39 PRINT X;"CUBER 1S-3XA3 
Suppose you input 9. 


Results: 


9 SQUARED IS 81 AND 9 CUBED IS 729 
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PRINT USING 
Statement 


Purpose: Prints strings or numbers using a specified format. 


Versions: Cartridge Disk Advanced Compiler 
* KK * Kk * * KK 


Format: PRINT USING v8; list of expressions [;|, | 
Remarks: 


v$ is a String constant or variable that 
consists of special formatting 
characters. These formatting characters 
determine the field and the format of 
the printed strings or numbers. 


list of expressions 
consists of the string or numeric >) 


expressions that are to be printed, 
separated by semicolons or commas. 


With PRINT USING, many common formatting 
tasks are simplified, such as aligning decimal points 
in numeric output. There are separate formatting 
characters for string and numeric data. Descriptions 
of each special formatting character and examples of 
their use are contained in the following pages. 
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PRINT USING 
Statement 


String Fields 


When PRINT USING is used to print strings, one of 
three formatting characters can be used to format the 
string field: 


! Specifies that only the first character in 
the given string is to be printed. 


\n spaces\ Specifies that 2 + n characters from the 
string are to be printed. If the 
backslashes are typed with no spaces, 
two characters are printed; with one 
space, three characters are printed, and 
so on. If the string is longer than the 
field, the extra characters are ignored. 
If the field is longer than the string, the 
string is left-justified in the field and 
padded with spaces on the right. 


& Specifies a variable-length string field. 
When the field is specified with ‘‘&’’, the 
string is output exactly as input. 


PRINT USING 
Statement 


This example shows how to use /and_ \ \ to print 
string fields. 


10 A$="LOOK":B$="0UT" 
20 PRINT USING "!";A$;B$ 
30 PRINT USING "\ \";A$;B$ 


Results: 


LO 
LOOKOUT 


This example demonstrates the use of “‘&”’ in 
conjunction with “!”’: 


19 A$="LOOK": B$="OUT" 


20 PRINT USING "!"5A$; 
30 PRINT USING "&";B$ 


Results: 


LOUT 
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Examples: 


PRINT USING 
Statement 


Numeric Fields 


When PRINT USING is used to print numbers, the 
following special characters can be used to format 
the numeric field: 


# A number sign is used to represent each 
digit position. Digit positions are always 
filled. If the number to be printed has 
fewer digits than positions specified, the 
number is right-justified (preceded by 
Spaces) in the field. 


A decimal point can be inserted at any 
position in the field. If the format string 
specifies that a digit is to precede the 
decimal point, the digit is always printed 
(as O if necessary). Numbers are 
rounded as necessary. For example: 


PRINT USING "##.##°;.78 


Results: 


0.78 


In this example, three spaces are inserted at the end 
of the format string to separate the printed values on 
the line. 


PRINT USING "##.## Ele os -06, 169, 234 
Results: 


10.20 5.39 66.79 9.23 
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PRINT USING 
Statement 


+ A plus sign at the beginning or end of 
the format string causes the sign of the 
number (plus or minus) to be printed 
before or after the number. 


PRINT USING "+##.## "3768595 ,2:8555.6,=;9 
Results: 
-68.95 +2.49 +55.60 -9.99 
- A minus sign at the end of the format 
field causes negative numbers to be 


printed with a trailing minus sign. 


PRINT: USING: "Ht. ##- . "3-68.95 22,4495 -7 81 


Results: 
68.95- 22.45 7. Gee “ 
ie A double asterisk at the beginning of 


the format string causes leading spaces 
in the numeric field to be filled with 
asterisks. The ** also specifies positions 
for two more digits. 


PRINT USING "**#.# "¢ 12.30 5"079 765.1 
Results: 


WIZ ee eee os. 76551 
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PRINT USING 
Statement 


A double dollar sign causes a dollar 
sign to be printed to the immediate left 
of the formatted number. The $$ 
specifies two more digit positions, one 
of which is the dollar sign. The 
exponential format cannot be used with 


$$. 
PRINT USING "$$###.##  "3456.78,0.9,-765.1 


Results: 
$456.78 $0.99 -$765.1@ 
sie The **$ at the beginning of a format 


string combines the effects of the above 
two symbols. Leading spaces are filled 
with asterisks, and a dollar sign is 

wy printed before the number. **$ 
specifies three more digit positions, one 
of which is the dollar sign. 


PRINT USING "**$##.##" 52.34 


Results: 


Ree. oe 


PRINT USING 
Statement 


A comma left of the decimal point in a 
formatting string prints a comma left of 

every third digit left of the decimal ‘> 
point. A comma at the end of the 

format string is printed as part of the 

string. A comma specifies another digit 
position. The comma has no effect if 

used with the exponential (AA AA) 

format. 


PRINT USING "####,.##°51234.5 
Results: 
1,234.59 
PRINT USING "####.##,°31234.5 


Results: 


1234.50, 


ANAA Four carets can be placed after the 
digit position characters to specify 
exponential format. The four carets 
allow space for E+nn or D+nn to be 
printed. Any decimal point position can 
be specified. The significant digits are 
left-justified, and the exponent is 
adjusted. Unless a leading + or trailing 
+ or - is specified, one digit position is 
used to the left of the decimal point to 
print a space or a minus sign. 


PRINT USING "##.##A AAA" 3234.56 “ 
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PRINT USING 
Statement 


Results: 


Ze 35E UZ 


PRINT USING ".###AAAA-";-88888 


Results: 
.889EG5- 


PRINT USING "+.##A AAA" 3123 


Results: 
+. 12E93 


An underscore in the format string 
causes the next character to be output 
as a literal character. 


PRINT USING "_!##.##_!°512.34 


Results: 


112.34! 
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PRINT USING 
Statement 
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The literal character itself can be an underscore by 
placing “ in the format string. 


If the number to be printed is larger than the 
specified numeric field, a percent sign (%) is printed 
in front of the number. If rounding causes the 
number to exceed the field, the percent sign is 
printed in front of the rounded number. 


PRINT USING "##.##" 5111.22 
Results: 

bli is22 

PRINT USING ".##"3;.999 
Results: 

1.00 


If the number of digits specified exceeds 24, an 
Illegal function call error occurs. 


This example shows how you can include string 
constants in the format string. 


PRINT USING "THIS IS EXAMPLE ##°; 1 
Results: 


THIS2 1S ERAMPLE #1 


& Purpose: 


Versions: 


Format: 


Remarks: 


PRINT# and PRINT# USING 
Statements 


Writes data sequentially to a file. 


Cartridge Disk Advanced Compiler 


* K * OK KK * KOK 


PRINT #filenum, [[USING x$;] list of exps] 


filenum is the number used when the file was 
opened for output. 


x$ is a String expression comprised of 
formatting characters as described in 
the previous entry, “PRINT USING 
Statement.”’ 


list of exps is a list of the numeric and/or string 
expressions that are written to the 
file. 


PRINT # does not compress data in the file. An 
image of the data is written to the file just as it would 
be displayed on the screen with a PRINT statement. 
For this reason, care should be taken to delimit the 


data in the file, so that it is input correctly from the 
file. 


In the list of expressions, numeric expressions should 
be delimited by semicolons. For example, 


PRINT #1 AsBsCstereZ 


(If commas are used as delimiters, the extra blanks 
inserted between print fields are also written to the 
file.) 


PRINT# and PRINT# USING 
Statements 


String expressions must be separated by semicolons 

in the list. To format the string expressions correctly 

in the file, use explicit delimiters in the list of ‘> 
expressions. _. 


For example, let A$=‘‘CAMERA” and 
B$=‘‘93604-1’’. The statement 


PRINT #1,A$5;B$ 


writes CAMERA93604-1 to the file. Because there 
are no delimiters, this could not be input as two 
separate strings. To correct the problem, insert 
explicit delimiters into the PRINT # statement as 
follows: 


PRINTG #1 AS: 5" 3BS 


The image written to the file is 


CAMERA ,93604-1 


which can be read back into two string variables. 


If the strings themselves contain commas, 
semicolons, significant leading blanks, carriage 
returns, or line feeds, write them to the file 
surrounded by explicit quotation marks using 
CHR$(34). 


For example, let A$=““CAMERA, AUTOMATIC” 
and B$=‘‘ 93604-1’’. The statement: 


PRINT #1,A$5;B$ 


writes the following image to the file: 


"CAMERA, AUTOMATIC""93604-1" 
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PRINT# and PRINT# USING 
Statements 


and the statement: 
INPUT #1,A$,B$ 


inputs the string ““CAMERA” to A$ and 
“AUTOMATIC 93604-1” to B$. 


To separate these strings properly in the file, write 
double quotes to the file image using CHR$(34). 
The statement: 

PRINT #1,CHR$(34) ;A$;CHR$(34) ;CHR$(34) ;B$;CHR$(34) 
writes the following image to the file: 

"CAMERA, AUTOMATIC" "936@4-1" 
and the statement: 


INPUT #1,A$,B$ 


inputs ‘““CAMERA, AUTOMATIC” to A$ and 
‘““93604-1” to BS. 


The PRINT # statement can also be used with the 
USING option to control the format of the file. For 
example: 


PRINT #1, USING" $$###.##,°303K3L 
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PRINT# and PRINT# USING 
Statements 


Example: Since data written to the file contains a dollar sign, 
use string variables to read them back, as in this 


example. “a 


19 A=123 

20 B=6789 

oy CeZ2 .33 

40 OPEN "DATA" FOR OUTPUT AS #1 

50 PRINT #1,USING "$$###.##,°3A5B;C 
6@ CLOSE 

7@ OPEN "DATA" FOR INPUT AS #1 

80 INPUT #1,A$,B$,C$ 

908 CLOSE 

190 PRINT A$,B$,C$ 
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ww Purpose: 


Versions: 


Format: 


Remarks: 


PSET and PRESET 
Statements 


Draws a point at the specified position on the screen. 


Cartridge Disk Advanced Compiler 


2 KK KK * KK * KK 


Graphics mode only. 
PSET (x,y) [attribute] 


PRESET (x,y) [attribute] 


(x,y) are the coordinates of the point to be set. 
They can be in absolute or relative form, 
as explained in “Specifying Coordinates”’ 
under ‘‘Graphics Modes” in BASTC 
Compiler 2.00 Fundamentals. 


attribute is an integer expression that chooses an 
attribute from the attribute range for the 
current screen mode. In SCREEN 1, 
(medium resolution), attribute can range 
from 0 to 3. In SCREEN 2, (high 
resolution), attribute can be O or 1. 


The default color attribute for the 
foreground is the maxiumum color 
attribute for that screen mode. 


The default color attribute for the 
background is always zero. 
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PSET and PRESET 
Statements 


346 


PRESET is almost identical to PSET. The only 


difference is that if no attribute parameter is given to 
PRESET, the background attribute (O) is selected. If 
attribute is included, PRESET is identical to PSET. 


Line 70 in the example below could just as easily be: 


7D PSETtR1 49 


Out-of-range coordinates are clipped, and no error 
occurs. 


Example: 


PSET and PRESET 
Statements 


Lines 20—40 of this example draw a diagonal line 
from the point (0,0) to the point (100,100). Lines 
60-80 erase the line by setting each point to a color 
of 0. 


19 
20 
39 
40 
oy!) 
60 
79 
80 


CLS: SCREEN. keer 
FOR I=@ TO 100 

Poet: {1 T) 

NEXT 

‘erase line 

FOR I=10@0 TO @ STEP -1 
PRESET(I,I1) 

NEXT 
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PUT 


Statement (Files) 


Purpose: 


Versions: 


Format: 


Remarks: 
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Writes a record from a random buffer to a random 
file. 


Cartridge Disk Advanced Compiler 


* OK KK * KOK * KK 


PUT [#|filenum |,number| 


filenum — is the number under which the file was 
opened. 


number — is the record number for the record to be 
written, in the range 1 to 16 megabytes. 


If number is omitted, the record has the next 
available record number (after the last PUT). 


PRINT #, PRINT # USING, WRITE #, LSET, and 
RSET can be used to put characters in the random 
file buffer before a PUT statement. In the case of 
WRITE #, BASIC pads the buffer with spaces up to 
the carriage return. 


Any attempt to read or write past the end of the 
buffer causes a Field overflow error. See also 
‘“BASIC Disk Input and Output,” in BASIC 
Compiler 2.00 Fundamentals. 


Because DOS blocks as many records as possible in 
512-byte sectors, the PUT statement does not 
necessarily perform a physical write to the disk for 
each record. See the Disk Operating System 
reference for more information on buffers and the 
CONFIG.SYS file. 


Example: 


PUT 
Statement (Files) 


PUT can be used for a communications file. In that 
case number is the number of bytes to write to the 
communications file. This number must be less than 
or equal to the value set by the LEN option on the 
OPEN ‘‘COM... statement. 


In DOS 2.10 and later versions, files can have up to 
16 megabytes. Random files in BASIC have fixed 
length records. The requested record number in a 
GET or PUT statement is multiplied by this fixed 
record length to form a 24-bit product. This value is 
then used to move the random file pointer by a DOS 
call to read or write the desired record. The 16 
megabyte value has some restrictions: 


e The total file size can be up to 16 megabytes, so 
the largest record number available is: 


16775616/record length 
e File size is limited by available disk space. 


See ““BASIC Disk Input and Output,” in BASIC 
Compiler 2.00 Fundamentals. 


PUT 


Statement (Graphics) 


Purpose: 


Versions: 


Format: 


Remarks: 
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Plots images on a specified area of the screen. “A 


Cartridge Disk Advanced Compiler 


* KK OK 2 OK 


Graphics mode only. 


PUT (x,y), array |,action| 


(x,y) are the coordinates of the top left corner 
of the image to be transferred. 


array is the name of a numeric array containing 
the information to be transferred. For 
more information on this array, see also 
‘““GET Statement (Graphics).”’ -) 


action is one of: 


XOR is the default. 


PUT is the opposite of GET in the sense that it takes 
data out of the array and puts it on the screen. 
However, it also provides the option of interacting 
with the data already on the screen. 


PSET simply stores the data from the array onto the “a 
screen, so this is the true opposite of GET. 


PUT 
Statement (Graphics) 


PRESET is the same as PSET except that a 
complementary image is produced. For example, in 
medium resolution, which has a maximum attribute 
of 3, an attribute of O in the array causes the 
corresponding point to be plotted with an attribute 
of 3, and vice versa; an attribute of 1 in the array 
causes the corresponding point to be plotted with an 
attribute of 2, and vice versa. 


AND, OR, and XOR specify the logical operations 
on the bits of each image. 


AND is used to display selected parts of an image. 
Only those areas where some image already exists 
are shown. 


OR is used to superimpose the transferred image 
onto the existing image. 


XOR is a special mode that can be used for 
animation. Its unique property is that when an image 
is PUT against a complex background twice, the 
background is restored unchanged. This allows you 
to move an object around without obliterating the 
background. 
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PUT 
Statement (Graphics) 


In medium resolution mode, AND, OR, and XOR 
have the following effects on color: 


Nb a. 


screen 


O 


screen 


0 
1 
2 
3 
R 
0 
1 
ys 
3 
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PUT 
Statement (Graphics) 


screen 


Animation of an object can be performed as follows: 


1. PUT the object on the screen (with XOR). 
2. Recalculate the new position of the object. 


3. PUT the object on the screen (with XOR) a 
second time at the old location to remove the 
old image. 


4. Repeat step 1, this time putting the object at the 
new location. 


Movement done this way leaves the background 
unchanged. Flicker can be reduced by minimizing 
the time between steps 4 and 1, and making sure 
there is enough time delay between steps 1 and 3. If 


more than one object is being animated, each object 
should be processed individually, one step at a time. 


PUT 
Statement (Graphics) 


If it is not important to preserve the background, 
animation can be performed using the PSET action 
verb. But you should remember to have an image 
area that contains the “‘before’’ and ‘“‘after’’ images 
of the object. This way the extra area effectively 
erases the old image. This method can be somewhat 
faster than the method using XOR described above, 
since only one PUT is required to move an object 
(although you must PUT a larger image). 


If the image to be transferred is too large to fit on 
the screen, an Illegal function call error occurs. 


Example: This example shows how to move a circle across the 
screen with XOR. 


10 CLS: DEFINT-A-Z:SCREEN TeKEY- GEF 
20 DIM A(4Q4) 

3@ CIRCLE (160,100), 20,3 

49 PAINT (160,100) ,2,3 “ 
50 GET (140,80)-(180,120) ,A:CLS 

60 X=3@0: Y=5@ 

7Q@ FOR I=1 TO 20 

80 PUT (X,Y),A,XOR 

90 PUT (X,Y),A,XOR 

100 X=X + 19 

11Q@ NEXT 
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© Purpose: 


Versions: 


Format: 


Remarks: 


RANDOMIZE 
Statement 


Reseeds the random number generator. 


Cartridge Disk Advanced Compiler 


kk 2 2k 2k 2k 2k * kk 


RANDOMIZE [n] 


RANDOMIZE TIMER 


n is an integer, single-precision, or 
double-precision expression that is used as the 
random number seed. 


If n is omitted, BASIC suspends program execution 
and asks for a value by displaying: 


Random Number Seed (-32768 to 32767)? 


before executing RANDOMIZE. 


If the random number generator is not reseeded, the 
RND function returns the same sequence of random 
numbers each time the program is run. To change 
the sequence of random numbers every time the 
program is run, place a RANDOMIZE statement at 
the beginning of the program and change the seed 
with each run. 


The internal clock can be a useful way to get a 
random number seed. You can use VAL to change 
the last two digits of TIME$ to a number, and then 
use that number for n. 


Ja2 


RANDOMIZE 
Statement 


You can get a new random number seed without 
being prompted. To do this, use the TIMER 
function in the expression. “ 


Examples: This example uses TIMER. Note that each time the 
program is run you see a different sequence of 
numbers. 


Note: The values you receive may be different. 
18 RANDOMIZE TIMER 
20 FOR I=1 TO 4 
30 PRINT RND; 
40 NEXT 
Results: 


First time 


9590051 .1936786 .1464037 .7754918 “A 


Second time 
.8261163 .17422 .9191545 .5041142 


The following example demonstrates how different 
values for the random number seed produce 
different number sequences. 


19 RANDOMIZE 
20 FOR I=1 TO 4 
38 PRINT RND; 
40 NEXT I 


Results: 


Random Number Seed (-32768 to 32767)? “ 
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RANDOMIZE 
Statement 


Suppose you respond with 3. The program 
continues: 


Random Number Seed (-32768 to 32767)? 3 
.9645035 .397242 .5.81904E-02 
. 3093355 


Random Number Seed (-32768 to 32767)? 


Suppose this time you respond with 4. The program 
continues: 


Random Number Seed (-32768 to 32767)? 4 
.2300828 .8036293 .2296571 .6990715 


Random Number Seed (-32768 to 32767)? 


If you try 3 again, you'll get the same sequence as 
the first run: 


Random Number Seed (-32768 to 32767)? 3 
.9645035 .397242 .5.81904E-02 
3003555 
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READ 
Statement 


Purpose: Reads values from a DATA statement and assigns ‘> 
them to variables. See ““DATA Statement.”’ 


Versions: Cartridge Disk Advanced Compiler 
** K * KK * KK * KK 


Format: READ variable |, variable)... 
Remarks: 


variable is a numeric or string variable or array 
element that is to receive the value read 
from the DATA table. 


A READ statement must always be used with a 

DATA statement. READ statements assign DATA 
statement values to the variables in the READ “a 
statement on a one-to-one basis. 


READ statement variables can be numeric or string, 
and the values that are read must agree with the 
variable types specified. If they do not agree, a 
Syntax error results. 


A single READ statement can access one or more 
DATA statements (they are accessed in order), or 
several READ statements can access the same 
DATA statement. If the number of variables in the 
list of variables exceeds the number of elements in 
the DATA statement(s), an Out of data error occurs. 
If the number of variables specified is fewer than the 
number of elements in the DATA statement(s), 
subsequent READ statements begin reading data at “ 
the first unread element. If there are no subsequent | 
READ statements, the extra data is ignored. 
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Examples: 


READ 
Statement 


To reread data from any line in the list of DATA 
statements, use the RESTORE statement. See 
‘““RESTORE Statement.” 


This program segment reads the values from the 
DATA statements into the array A. After execution, 
the value of A(1) is 3.08, and so on. 


19 FOR I=1 TO 19 

20 READ A(1I) 

30 NEXT I 

49 DATA 3.98,5.19,3.12,3.98,4.24 
58 DATA 5.08,5.55,4.00,3.16,3.37 


This program reads string and numeric data from 
the DATA statement in line 30. Note that you do 
not need quotation marks around COLORADO, 
because it does not have commas, semicolons, or 
significant leading or trailing blanks. However, you 
do need the quotation marks around ‘“‘DENVER,”’ 
because of the comma. 


19-PRINT . "CITY eee eo ZIPS 
20 READ C$,S$,Z 

30 DATA "DENVER," , COLORADO, 80211 
40 PRINT C$,S$,Z 


Results: 
Carry STAT. ZIP 
DENVER, COLORADO 80211 
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REDIM 
Statement 


Purpose: Changes the space allocated to an array that has ‘> 
been declared dynamic. 


Versions: Cartridge Disk Advanced Compiler 
* KK 


Format: REDIM [SHARED] variable(subscripts) 
|, variable(subscripts) |... 


Remarks: 
SHARED allows you to share variables 
among all subprograms in a 
module. 
variable is the name of the array you want 
to redimension. “ 


subscripts is a list of numeric expressions, 
separated by commas, that define 
the dimensions of the array. 


The REDIM statement changes the space allocated 
to an array that has been declared dynamic. Static 
arrays cannot appear in a REDIM statement. 


The SHARED attribute allows arrays to be shared 
globally by the main program and all subprograms 
within a module. To declare all variables as global 
variables, place the word “SHARED” directly after 
the word “REDIM.” This differs from the SHARED 
statement. The SHARED statement only affects 
variables within a single subprogram. For more 
information, see “SHARED Statement.” 
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REDIM 
Statement 


The number of subscripts must be the same in the 
redimensioned array as in the original array. The 
following example demonstrates an illegal REDIM: 


10 DIM MONTH$(12), TME(12,60) 
20 REDIM MONTH$(12), TME(12,60,60) 


The above example is illegal because the array in 
line 20 has three dimensions declared, but the 
original array has two dimensions declared. 


When a REDIM statement is compiled, all the array 
declarations in the statement are treated as dynamic 
arrays. At runtime, when a REDIM statement is 
executed, the array is deallocated, if it is currently 
allocated, and is the reallocated with the new 
dimensions. Old array element values are lost. 
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REDIM 
Statement 


Example: This example demonstrates the use of static and 
dynamic arrays within the same program. 


FeO SS TALIC 

130 DIM C(5,5) 

149 C(5,5)=1 

145 C=5 

150 ERASE C 

160 PRINT C,C(5,5) 

179 1 = 20 

180 ' $DYNAMIC 

199 DIM A(I,I,1) 

200 I = 49 

210 DIM B(I,1) 

220 ' ASSIGN VALUES INTO B 
225° BC1 4) 32: 49 

227 ' ERASE AND REDIMENSION A 
230 ERASE A 

240 REDIM A(5,5,5) 


go0 Pl lip = 3 
260 PRINT B(1,1),A(1,1,1) “ 
270 END - 
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ww Purpose: 


Versions: 


Format: 


Remarks: 


REM 
Statement 


Inserts explanatory remarks in a program, or inserts 
compiler metacommands. 


Cartridge Disk Advanced Compiler 


REM remark | metacommand 


remark can be any sequence of characters. 


metacommand is the name of one of the special 
commands that control the operation 
of the compiler. All compiler 
metacommands begin with the $ 
(dollar sign) character. See 
‘“Compiler Metacommands”’ in 
BASIC Compiler 2.00 Fundamentals 
for more information. 


REM statements that do not contain compiler 
metacommands are not executed, but are displayed 
when the program is listed exactly as they were 
entered. However, they do slow execution time 
somewhat and take up memory space. 


REM statements can be branched into (from a 
GOTO or GOSUB statement), and execution 
continues with the first executable statement after 
the REM statement. 


Remarks can be added by preceding the remark with 
a single quotation mark instead of :REM. If you put 
a remark on a line with other BASIC statements, the 
remark must be the /ast statement on the line. 
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REM 
Statement 


You cannot use the single quote (’) to add comments 
at the end of a DATA statement. If you do, BASIC 
thinks it is part of a string. You can, however, use 
REM to add a remark. 


Examples: This example shows the two ways to insert remarks 
in a program. 


10 ‘calculate average velocity 
20 SUM=@: REM initialize SUM 


30 FOR I=1 TO 20 
40 SUM=SUM + V(I) 


Line 20 might also be written: 


20 SUM=@ ' initialize SUM 


The following example includes a compiler a 
metacommand. 


1000 REM $LINESIZE: 120 
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oe Purpose: 


Versions: 


Format: 


Remarks: 


RESET 
Command 


Closes all disk files and clears the system buffer. 


Cartridge Disk Advanced Compiler 


*K OK OK 6 K 26 OK OK 


RESET 


If all open files are on disk, RESET is the same as 
CLOSE with no file numbers after it. 
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RESTORE 
Statement 


Purpose: Allows DATA statements to be reread from a 
specified line or label. 


Versions: Cartridge Disk Advanced Compiler 


Format: RESTORE [line | label] 
Remarks: 


line is the line number of a DATA statement in 
the program. 


label is asequence of 1 to 40 letters, digits, or 
periods, in any combination, followed by a 


colon. “ 


The use of mnemonic labels makes your 
programs easier to read and maintain. Labels 
can be used as objects of most statements 
where line numbers are currently permitted, 
with the following exceptions: 


IF (condition) THEN (line number) 

and 

RUN (line number) 
In each of these cases, only a line number is 
permitted in the statement. However, for 
both of these cases, the explicit use of a 


GOTO statement allows a label to be used. a 
For example: 


IF A>10 THEN GOTO BAD.DATA 
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RESTORE 
Statement 


To distinguish labels from keywords or 
variables, each label must be followed by a 
colon (:) when it starts a line. 


Note: If you wish to use error reporting 
(with the /E option) and error trapping, 
you must use line numbers. 


Numeric labels, alphanumeric labels, and line 
numbers can be intermixed in the same 
program, and numeric or alphanumeric labels 
may be used without the /N switch. 


After a RESTORE statement is executed, the next 
READ statement accesses the first item in the first 
DATA statement in the program. If /ine or label is 
specified, the next READ statement accesses the 
first item in the specified DATA statement. 


In this example, the RESTORE statement in line 20 
resets the DATA pointer to the beginning so that the 
values that are read in line 30 are 57, 68, and 79. 


10 READ A,B,C 

20 RESTORE 

3@ READ D,E,F 

40 DATA 57, 68, 79 
50-PRINT “AS Bs C20 eese 


Results: 


a) OS = 79 by ae ery 
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RESUME 
Statement 


Purpose: Continues program execution after an error recovery ‘> 
procedure. 


Versions: Cartridge Disk Advanced Compiler 


(**) (**) (**) 4K 
Format: RESUME [0] 

RESUME NEXT 

RESUME [ine | label 


Remarks: Any of the formats shown above can be used, 
depending on where execution is to resume: 


RESUME or RESUME 0 
Execution resumes at the statement “» 
that caused the error. 

RESUME NEXT 
Execution resumes at the statement 
immediately following the one that 
caused the error. 


RESUME line 
Execution resumes at the specified 
line number. 


RESUME label 
Execution resumes at the specified 
label. A label is a sequence of 1 to 40 
letters, digits, or periods, in any 
combination followed by a colon. “a 
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RESUME 
Statement 


The use of mnemonic labels makes your programs 
easier to read and maintain. Labels can be used as 
objects of most statements where line numbers are 
currently permitted, with the following exceptions: 


IF (condition) THEN (line number) 
and 
RUN line number) 


In each of these cases, only a line number is 
permitted in the statement. However, for both of 
these cases, the explicit use of a GOTO statement 
allows a label to be used. For example: 


IF A>10 THEN GOTO BAD.DATA 


To distinguish labels from keywords or variables, 
each label must be followed by a colon (:) when it 
Starts a line. 


Note: If you wish to use error reporting (with 
the ERL variable) and error trapping, you must 
use line numbers. 


Numeric labels, alphanumeric labels, and line 
numbers can be intermixed in the same program, and 
numeric or alphanumeric labels may be used without 
the /N switch. 
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RESUME 
Statement 
A RESUME statement that is not in an error trap 


routine causes a RESUME without error message to 
occur. 


Note: If your program contains any ON 
ERROR or RESUME statements, you need to 
compile using the /X or /E parameter. See 
‘‘Compiler Parameters” in BASIC Compiler 
2.00 Fundamentals for more information. 


Example: In this example, line 1000 is the beginning of the 
error trapping routine. The RESUME statement 
causes the program to return to line 80 when error 
230 occurs in line 90. 


19 ON ERROR GOTO 1000 


1000 IF (ERR=23@)AND(ERL=9@) THEN PRINT “a 
"TRY AGAIN": RESUME 8@ 
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RETURN 
Statement 


LY Purpose: Stops a subroutine and returns to the main program. 
See ‘““GOSUB and RETURN Statements.”’ 


Versions: Cartridge Disk Advanced Compiler 


Format: RETURN [Jine] | label 
Remarks: 


line is the number of the program line you wish to 
return to. 


label is the label you wish to return to. A label is a 
sequence of 1 to 40 letters, digits, or periods, 
in any combination. 


The use of mnemonic labels makes your 
programs easier to read and maintain. Labels 
can be used as objects of most statements 
where line numbers are currently permitted, 
with the following exceptions: 


IF (condition) THEN (line number) 
and 


RUN Jine number) 
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RETURN 
Statement 


In each of these cases, only a line number is 
permitted in the statement. However, for 
both of these cases, the explicit use of a 
GOTO statement allows a label to be used. 
For example: 


IF A>10 THEN GOTO BAD.DATA 


To distinguish labels from keywords or 
variables, each label must be followed by a 
colon (:) when it starts a line. 


Note: If you wish to use error reporting 
(with the ERL variable ) and error 
trapping, you must use line numbers. 


Numeric labels, alphanumeric labels, and line 

numbers can be intermixed in the same 

program, and numeric or alphanumeric labels - 
may be used without the /N switch. 


Although you can use RETURN line | /abe/ to return 
from any subroutine, this enhancement was added to 
allow nonlocal returns from the event trapping 
routines. From one of these routines you will often 
want to go back to the BASIC program at a fixed 
line number while still eliminating the GOSUB entry 
the trap created. The nonlocal RETURN must be 
used with care, however, since any other GOSUB, 
WHILE, or FOR statements active at the time of the 
trap remain active. 
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RIGHTS 
Function 


w Purpose: _ Returns the rightmost n characters of string x$. 


Versions: Cartridge Disk Advanced Compiler 
KK ** > KK ** KK 


Format: v$ = RIGHTS$(x8,n) 
Remarks: 
is any string expression. 
is an integer expression in the range O to 


32767 that specifies the number of characters 
to be in the result. 


If n is greater than or equal to LEN(x8), x$ is 
returned. If n is zero, the null string (length zero) is 
returned. 


See also ‘‘MID$” and ‘“‘LEFT$” functions. 


Example: In this example, the rightmost seven characters of the 
string A$ are returned. 


19 A$="BOCA RATON, FLORIDA" 
20 PRINT RIGHT$(A$,7) 


Results: 


FLORIDA 


RMDIR 
Command 


Purpose: 


Versions: 


Format: 


Remarks: 


Examples: 
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Removes a directory from the specified disk. 


Cartridge Disk Advanced Compiler 


* KK 2 OK KO KK 


RMDIR path 


path is a string expression, not exceeding 63 
characters, that identifies the subdirectory 
to be removed from the existing directory. 
See also “Naming Files” and 
“Tree-Structured Directories” in BASIC 
Compiler 2.00 Fundamentals for more 
information. 


The directory must be empty of all files and 
subdirectories before it can be removed, with the 
exception of the ‘‘.”’ and “‘..’”’ entries, or a Path/file 
access error occurs. 


The examples on the next page refer to the tree 
structure shown below. 


ROOT 
ee 
DOS a 
DOS21 DOS30 BASIC FORTRAN PASCAL 
INT COMPILER 


RMDIR 
Command 


If you are in the root directory and you want to 
remove the directory called DOS30, use: 


RMDIR "DOS\DOS30" 


If you want to make LANG the current directory 
and remove the directory called FORTRAN, use: 


CHDIR "LANG" 
RMDIR "FORTRAN" 


Another way to remove the directory FORTRAN is 
to make the root the current directory and then 
remove FORTRAN. 


CHOTR. A." 
RMDIR "LANG \ FORTRAN" 


The directory preceding the current directory 
cannot be removed. Using the same tree structure, 
suppose that DOS20 is the current directory. If you 
try to remove the DOS directory, you get a Path/file 
access error. 


If you try to use the KILL command to remove a 
directory, you get a Path/file access error. 
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RND 
Function 


Purpose: Returns a random number between 0 and 1. 


Versions: Cartridge Disk Advanced Compiler 
* KK * OK * ok 2 K 


Format: v= RND[(x)] 
Remarks: 


x is a numeric expression that affects the 
returned value as described below. 


The same sequence of random numbers is generated 

each time the program is run unless the random 

number generator is reseeded. Reseeding is most 

easily done by using the RANDOMIZE statement. 

See “RANDOMIZE Statement.” “~ 


You can also reseed the generator when you call the 
RND function by using x where x is negative. This 
always generates the particular sequence for the 
given x. This sequence is not affected by 
RANDOMIZE, so if you want it to generate a 
different sequence each time the program is run, you 
must use a different value for x each time. 


If x is positive or not included, RND(x) generates the 
next random number in the sequence. 


RND(O) repeats the last number generated. 


To get random numbers in the range zero through n, 
use the formula: 


INT(RND * (n+1)) 
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Example: 


RND 
Function 


In this example, the first horizontal line of results 
shows three random numbers, generated using a 
positive x. 


In line 40, a negative number is used to reseed the 
random number generator. The random numbers 
produced after this reseeding are in the second row 
of results. 


In line 80, the random number generator is reseeded 
using the RANDOMIZE statement; in line 90 it is 
reseeded again by calling RND with the same 
negative value as in line 40. This cancels the effect of 
the RANDOMIZE statement, as you can see; the 
third line of results is identical to the second line. 


In line 130, RND is called with an argument of 0, so 
the last number printed is the same as the preceding 
number. 


19 FOR I=1 T0 3 

20 PRINT RND(1); ' x>Q 
30 NEXT I 

40 PRINT: X=RND(-6) ' x<@ 
599 FOR I=1 TQ 3 


6% PRINT RND(I); ' x>Q 
7@ NEXT I 
88 RANDOMIZE 853 ' randomize 


9@ PRINT: X=RND(-6) ' x<@ 

10@ FOR I=1 TO 3 

11@ PRINT RND; ' same as x>@ 
12Q0 NEXT I 

130 PRINT: PRINT RND(Q) 
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RND 
Function 


Results: 


AGPTIO09: -1 78808.’ 543805 
-1593488 .815697 . 856357 
.1593488 .815697 896397 
. 856357 


Reseeding with the RND (negative number) 
function reseeds through permutation of the last 
floating-point temporary. Since no floating-point 
calculations are done in this example, the new seed is 
always the same. 


19 DEFINT A-Z 
20 FOR J=1 T0 5 


30 X=RND(-J) 
40 FOR I=1 TO 5:PRINT RND;NEXT: PRINT 
5Q@ NEXT J 


If line 20 is changed to: -) 


20 FOR Wah Te STEP <1 


a new seed is generated each time. 
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YY Purpose: 


Versions: 


Format: 


Remarks: 


RUN 
Command 


Begins execution of a program. 


Cartridge Disk Advanced Compiler 


6 OK OK * KK 7 OK 


RUN line 

RUN filespec 

line is the line number of the program where 
you want execution to begin. 

filespec is a string expression for the file 


specification. It can contain a path. 
Filespec must conform to the rules 
outlined under ‘‘Naming Files”’ in 
BASIC Compiler 2.00 Fundamentals; 
otherwise, an error occurs. 


RUN or RUN Jine begins execution of the program. 
If /ine is specified, execution begins with the 
specified line number. Otherwise, execution begins 
at the lowest line number. 


RUN /filespec loads a file from disk into memory and 
runs it. It closes all open files and deletes the current 
contents of memory before loading the designated 
program. See also ““BASIC Disk Input and Output’’ 
in BASIC Compiler 2.00 Fundamentals. 


Executing a RUN command turns off any sound that 
is running and resets to Music Foreground. Also, 
PEN and STRIG are reset to OFF. 
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RUN 


Command 


Examples: 


This is an example of RUN line -) 


10 
20 
30 
40 
50 
60 
79 
80 


A=1 

B=2 

C=3 

D=4 

PRINT A,B,C,D 
IF D=@ THEN END 
RUN 590 

END 


Results: 


© Po 
CO Ww 
oO - 


Note: All variables and strings are reset to 
zero or nulls when the RUN statement is 
executed. 


As an example of RUN /filespec, change line 70 to 
read: 


70 RUN "NEXTPGM.EXE" 


The program would look like: 


19 
20 
30 
49 
50 
60 
79 
80 
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A 
B 
C 
D 
PRINT A,B,C,D 

IF D=@ THEN END 


RUN "“NEXTPGM.EXE" 
END 


RUN 


Command 
NEXTPGM.BAS looks like: 
YY 19 PRINT A,B,C,D 

20 END 

Results: 

1 2 3 4 
(clear screen) 

0 ) 0 0 


Note: You must first compile and link 
NEXTPGM.BAS in order to create 
NEXTPGM.EXE. You cannot RUN a BASIC 
interpreter application with this statement. For 
instance, the following program line: 


70 RUN "NEXTPGM.BAS" 


is legal in the BASIC Interpreter environment, 
however, unpredictable errors will result in the 
BASIC Compiler environment because .BAS is 
not recognized as an executable filetype. The 
file extensions recognized as executable by the 
compiler are .BAT, .COM and .EXE. 
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SCREEN 
Function 


Purpose: Returns the ASCII code (0-255) for the character on a) 
the active screen at the specified row (line) and 
column. 


Versions: Cartridge Disk Advanced Compiler 
** kK ** OK 7 OK * ok 


Format: v = SCREEN(row,col[,z]) 
Remarks: 
row iS a numeric expression in the range | to 25. 


If the soft key display is turned on, however, 
only 24 rows are available. 


col is a numeric expression in the range 1 to 40 or 
1 to 80, depending on the WIDTH setting. “ 


Zz is a numeric expression that evaluates to a 
true or false value. z is valid only in text 
mode. 


For a list of ASCII codes, See Appendix B, “‘ASCII 
Character Codes.”’ 


In text mode, if z is included and is true (nonzero), 

the color attribute for the character is returned 

instead of the code for the character. The color 

attribute is a number in the range 0 to 255. This 

number, v, is deciphered as follows: ~ 


(v MOD 16) is the foreground attribute. 
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SCREEN 
Function 


((v \16) MOD 8) is the background attribute, 
where foreground is calculated as above. 


If (v>127), character is blinking; false (0), if it 
is not. 


For a list of colors and their associated attributes, see 
the ‘““COLOR Statement.”’ 


In graphics mode, if the specified location contains 
graphic information (points or lines, not just a 
character), the SCREEN function returns 0. 


Any values entered outside the ranges indicated 
result in an Illegal function call error. 


The SCREEN statement is explained in the next 
entry. 


In this example, if the character at 10,10 is A, X is 
3. 


100 X = SCREEN (10,19) 


This example returns the color attribute of the 
character in the upper left corner of the screen. 


110 X = SCREEN7iE1.)) 
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SCREEN 
Statement 


Purpose: Sets the screen attributes to be used by subsequent ‘eo, 
statements. 


Versions: Cartridge Disk Advanced Compiler 
2k 3k kK 2K kK 


Meaningful with the Color/Graphics Monitor 
Adapter only. 


Format: SCREEN [mode] [,[ burst] |,[apage| 
[,vpage]| 


Remarks: 


mode is a numeric expression resulting in an 
integer value of 0, 1, or 2. Valid modes 
are: 


0 Text mode at current width (40 or 
80). 


1 Medium resolution graphics mode 
(320x200). Use only with 
Color/Graphics Monitor Adapter. 


2 High resolution graphics mode 


(640x200). Use only with 
Color/Graphics Monitor Adapter. 
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burst 


SCREEN 
Statement 


is a numeric expression resulting in a true 
or false value. It enables or disables color. 
On an RGB monitor, color burst is always 
on. On acomposite monitor, color burst 
can be on or off. 


In text mode (mode=0), a false (zero) 
value disables color (only the 
monochrome images are displayed); a true 
(nonzero) value enables color (color 
images are displayed). In medium 
resolution graphics mode (mode=1), a true 
(nonzero) value disables color, and a false 
(zero) value enables color. 


Because high resolution graphics are only 


two colors (black and white), this 
parameter has no effect in high resolution. 
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SCREEN 
Statement 


apage 


386 


(active page) is an integer expression in 
the range O to 7 for width 40; O to 3 for 
width 80. It selects the page to be written 
to by output statements to the screen, and 
is valid only in text mode (mode=0). 


SCREEN 
Statemen 


vpage (visual page) selects the page to be 
displayed on the screen, in the same way 
as apage above. The visual page can be 
different from the active page. vpage is 
valid only in text mode (mode=0). If 
omitted, vpage defaults to apage. 
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SCREEN 
Statement 


|Mode | Descrip _| Width | Psize | Colors _ 
0 | Alpha | 40,80 | 2k4e 116 
[1 [sz0x400 [ao fis [4 
(2 e40em00 | 80 tee 


If all parameters are valid, the new screen mode is 
stored; the screen is erased; the foreground color is 
set to white; and the background and border colors 
are set to black. 


If the new screen mode is the same as the previous 
mode, and color burst does not change, nothing is 
changed. 


If only apage and vpage are specified, display pages 
are changed for viewing. Initially, both active and 
visual pages default to 0 (zero). By manipulating 
active and visual pages, you can display one page 
while building another. You can then switch visual 
pages instantaneously. 


If you mix text and graphics in the 40 or 80 column 
graphics mode and are not using a U.S. keyboard, 
refer to “GRAFTABL Command” in the Disk 
Operating System Reference for information 
regarding additional character support with the 
Color/Graphics monitor. 
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Examples: 


SCREEN 
Statement 


Note: Only one cursor is shared among all the 
pages. If you are going to switch active pages 
back and forth, you should save the cursor 
position on the current active page (using 
POS(0) and CSRLIN), before changing to 
another active page. When you return to the 
original page, you can restore the cursor position 
using the LOCATE statement. 


Any parameter can be omitted. Omitted parameters, 
except vpage, assume the old value. 


Any values entered outside the ranges indicated 
result in an Illegal function call error. Previous values 
are retained. 


This example selects text mode with color burst 
enabled, and sets active and visual page to O. 


10 SCREEN 0,1,0,@ 

In this example, mode and color burst remain 
unchanged. Active page is set to 1 and display page 
tog. 


Le SOURCE 451,52 
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SCREEN 
Statement 


This example switches to high resolution graphics 
mode. 


19 SCREEN 2,,0,0 


This example switches to medium-resolution color 
graphics, color burst enabled. 


19 SCREEN 1,9 
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SGN 


Function 
Purpose: Returns the sign of x. 
Versions: Cartridge Disk Advanced Compiler 
** OK * KK * KO * 

Format: v = SGN(x) 
Remarks: «x is any numeric expression. 

SGN(x) is the mathematical signum function: 

e If x is positive, SGN(x) returns 1. 

« If xis zero, SGN(x) returns 0. 

e If xis negative, SGN(x) returns -1. 
Example: This example branches to 100 if X is negative; 200 if 
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X is zero; and 300 if X is positive. 


ON SGN(X)+2 GOTO 100,200,300 


YY Purpose: 


Versions: 


Format: 


Remarks: 


SHARED 
Statement 


Allows a subprogram to access variables declared in 
the main program without passing them as 
parameters. 


Cartridge Disk Advanced Compiler 


6 KK 


SHARED variable|()], [ variable| QO], ...] 


variable is the name of any simple variable or 
array declared at the main program level. 


To specify an array, include empty parentheses 
following the variable name. 


Variables and arrays referenced inside a subprogram 
are considered local to that subprogram and initial 
values of 0 are assumed. 


A variable must first be declared in the main 
program, or in a DIM statement before it can be 
referenced in a SHARED statement. 


By using either the SHARED statement ina 
subprogram, or the SHARED attribute to the 
COMMON, DIM, or REDIM statements at the main 
program level of the module, you can access 
variables without passing them into a subprogram as 
parameters. The SHARED attribute is used for 
sharing variables among all subprograms in a module, 
while the SHARED statement affects variables 
within a single subprogram. 
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SHARED 
Statement 


The SHARED statement must appear only inside a 
named subprogram (see the ‘“SUB/END SUB 
Statement’). If it occurs outside a subprogram, a “> 
(SB) error occurs. | 


Example: The following program calculates the area of a 
chosen shape. By making use of shared variables, 
the area for a different shape from the one chosen 
can be calculated without re-entering the dimensions. 


200 REM AREA CALCULATION PROGRAM 

219 CLS 

220 PRINT "AREA CALCULATION" 

230 PRINT: PRINT “1. RECTANGLE" 

240 PRINT "2. SQUARE" 

250 PRINT "3. TRIANGLE" 

260 PRINT "4. EXIT" 

Z7@- PRINT. Meee SELECTION: °; 

280 FIG$=INKEY$: IF FIG$ = "" THEN 2890 
290 IF ASC(FIG$) < 49 OR ASC(FIG$) > 52 THEN 280 
300 IF FIG$ = °4" THEN 409 

gEBCCES 

320 1NPUl “Emer CASE: " ; BSE 

330 IF FIG$ = "2" THEN 359 

340 INPUT “ENTER HEIGHT: " ; HGHT 

350 CALL CALCAREA 

360 PRINT "AREA = "3; AREA 

370 LOCETE 23.1: PRINT "PRESS ANY KEY 10 CONTINUE” 
380 S$ = INKEYS: -IF S$ = "" THEN: 368 
398 GOTO 2190 

400 END 

410 REM **** AREA SUBPROGRAM **** 

420 SUB CALCAREA STATIC 

43@ SHARED AREA, BSE, HGHT, FIG$ 

440 ON VAL(FIG$) GOTO 450, 470, 490 
450 AREA = BSE * HGHT 

460 GOTO 500 

470 AREA = BSE — 2 

480 GOTO 500 “ 
499 AREA = (BSE * HGHT) / 2 

098 END SUB 
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YU Purpose: 


Versions: 


Format: 


Remarks: 


SHELL 
Statement 


Loads COMMAND.COM and performs DOS 
functions. 


Cartridge Disk Advanced Compiler 


OK ** K * K 


SHELL [command string | 


command string 1S a String expression containing 
the name of a program to run, 
and, optionally, any parameters 
you are passing to the child 
process. 


Any program executed under a BASIC program is 
referred to as a child process. When the child 
process has finished executing, control returns to the 
parent BASIC program at the statement following 
the SHELL statement. 


Child processes are executed by SHELL loading and 
running a copy of COMMAND.COM with the /C 
switch. By using COMMAND in this way, any 
parameters you can have are correctly passed into 
the default File Control Blocks. Standard input and 
output can be redirected, and built-in commands 
such as DIR and PATH can be executed. If you 
enter SHELL with no command string, a copy of 
COMMAND.COM is loaded, the DOS prompt 
appears, and you can enter any commands that are 
valid under DOS (DIR, COPY, etc.). 


395 


SHELL 
Statement 
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You can return to the BASIC program by typing the 
word EXIT. You can also invoke batch files from 
the SHELL statement. To return to the parent ‘o) 
BASIC program, your batch file must contain EXIT 

as the last statement of the batch file. 


When running child processes from a BASIC 
application using the SHELL statement, there are 
some procedures and rules that your application 
should follow. Going outside the boundaries of these 
guidelines could cause your application to fail or 
produce unpredictable results. 


To guarantee that you return to your BASIC 
program from your child process in the screen mode 
that you expect, you can do one of two things: 


‘ Use BIOS Interrupt 10H, function call 15, to 
save the current video mode. When your child 
process returns to DOS, use function call 0 to a) 
restore the video mode. 


e From your BASIC program, execute a SCREEN 
statement followed by a CLS statement 
immediately after the SHELL statement. 


Before a BASIC program executes a SHELL 
statement, it saves any interrupt vectors it uses. 
However, interrupt vectors your routines use (but 
are not used by the BASIC program) are not 
restored. So be sure to save any interrupt vectors 


your routine uses to preserve the proper interface to 
DOS. 


SHELL 
Statement 


A child process that alters any file opened by the 
BASIC application can have unpredictable results. If 
you must update such files, be sure to close them 
from your BASIC application before executing a 
SHELL to your child process. Remember, files that 
were opened under the redirection of standard input 
and output constitute OPEN files. These files should 
not be modified using the SHELL process. 


Any routine that you execute from the SHELL 
Statement should never terminate and stay resident. 
If this procedure is attempted, the following can 
occur: all files close, the error message Can’t continue 
after SHELL prints, and control returns to DOS. 


The BASIC program remains in memory while the 
child process is running. When the child process 
finishes, the BASIC program continues. 


A program name in command string can have any 
extension you choose. If you do not supply an 
extension, DOS looks for a .COM extension, then a 
.EXE extension, and finally a .BAT extension. If the 
filename is not located during this search, 
COMMAND issues an error message. 


Any text separated from a program name supplied in 
command string by at least one blank is processed as 
program parameters. 


BASIC applications inherit their environments from 
DOS. Any changes your application makes to the 
environment are reflected in the environment for the 
child process. 


Note: For more information on environment, 
see “‘Detailed Descriptions of Advanced DOS 
Commands” in the Disk Operating System 
manual. 
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SHELL 
Statement 


You cannot SHELL to BASIC Interpreter, or any 
BASIC compiled program. If you attempt to run 
BASIC as a child process, you receive an error “ 
message. After this message is displayed, control 

returns to the BASIC parent. 


Make sure that your system has enough available 
memory to load any programs that you want to run 
as child processes. An attempt to run a child process 
with insufficient free memory causes an Out of 
Memory error. 


Examples: 


The following example displays a disk directory from 
your compiled program. 


1@@ SHELL 
A>DIR (type DIR command at DOS prompt) 
A>EXIT (type EXIT to return to program) 


The same result can be achieved with: 


100 SHELL "DIR" 


The next example creates a file, exits to the DOS 
SORT utility, and returns to the BASIC application. 


10 OPEN "SORTIN.DAT" FOR OUTPUT AS #1 
20 ‘writes data to be sorted 


10¢-CLOSE 3 

11@ SHELL “SORT <SORTIN.DAT >SORTOUT.DAT" 

120 OPEN "SORTOUT.DAT" FOR INPUT AS #1 

13Q@ ‘processes the sorted data “aw 


ww Purpose: 


Versions: 


Format: 


Remarks: 


Example: 


SIN 
Function 


Calculates the trigonometric sine function. 


Cartridge Disk Advanced Compiler 


** OK * KK * kK * KK 


v = SIN(x) 
x is an angle in radians. 


To convert degrees to radians, multiply by PI/180, 
where PI=3.141593. 


This example calculates the sine of 90 degrees after 
first converting the degrees to radians. 


19 PI=3.141593 
20 DEGREES = 99 


30 RADIANS=DEGREES * PI/18@ ° PI/2 
49 PRINT SIN(RADIANS) 


Results: 


] 
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SOUND 
Statement 


Purpose: Generates sound through the speaker. 


Versions: Cartridge Disk Advanced Compiler 


Format: SOUND freq, duration 


Remarks: 


freq is the desired frequency in Hertz (cycles 
per second). It must be a numeric 
expression in the range 37 to 32767. 


duration is the desired duration in clock ticks. 
The clock ticks occur 18.2 times per 
second. duration must be a numeric 
expression. Duration is .0015 to 65535. 


SOUND 
Statement 


When the SOUND statement produces a sound, the 
program continues to execute until another SOUND 
statement is reached. If duration of the new SOUND 
statement is O, the currently running SOUND 
statement is turned off. Otherwise, the program 
waits until the first sound completes before it 
executes the new SOUND statement. 


You can cause the sounds to be buffered so 
execution does not stop when a new SOUND 
statement is encountered. 


If a SOUND statement is followed immediately by 
an END statement, the sound being produced stops 


upon execution of the END statement and the 
SOUND buffer is flushed. 


See the explanation of the MB (Music Background) 
command under ‘“‘PLAY Statement.”’ 


If no SOUND statement is running, SOUND x,0 has 
no effect. 
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SOUND 


Statement 
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The tuning note, A, has a frequency of 440. The 


SOUND 
Statement 


following table correlates notes with their 
frequencies. 


C 
D 
i 
3 
G 
A 
B 
& 
D 
a 
ia 
G 
A 
B 


*middle C. 


130.810 
146.830 
164.810 
174.610 
196.000 
220.000 
246.940 
261.630 
293.660 
329.630 
349.230 
392.000 
440.000 
493.880 


DrPOMMONBDSPOaATMUN 


323.250 
587.330 
659.260 
698.460 
783.990 
880.000 
987.770 
1046.500 
1174.700 
1318.500 
1396.900 
1568.000 
1760.000 
£975.500 


Higher (or lower) notes can be approximated by 
doubling (or halving) the frequency of the 
corresponding note in the previous (next) octave. 


To create periods of silence, use SOUND 
32767,duration. 


The duration for one beat can be calculated from 
beats per minute by dividing the beats per minute 


into 1092 (the number of clock ticks in a minute). 


SOUND 
Statement 


Examples: The following program creates a glissando (sliding up 
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The next table shows typical tempos in terms of 


clock ticks: 


Tempo Beats/ Ticks/ Beat 
Minute 


very slow Larghissimo 


Largo 
Larghetto 
Grave 
Lento 
Adagio 


Adagietto 
Andante 


Andantino 
Moderato 


Allegretto 
Allegro 
Vivace 
Veloce 
Presto 


very fast Prestissimo 


and down the scale). 


40-60 
60-66 


66-76 


76-108 


108-120 


120-168 


168-208 


FOR 1=440 TO 1900 STEP 5 


SOUND I, @.5 
NEXT 


FOR I=19@@ TO 440 STEP -5 


SOUND I, @.5 
NEXT 


27.3-18.2 
18.2-16.55 


16.55-14.37 


14.37-10.11 


10.11-9.1 


9.1-6.5 


6.5-5.25 


SOUND 
Statement 
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SPACES 


Function 
Purpose: Returns a string consisting of n spaces. 
Versions: Cartridge Disk Advanced Compiler 
se ee 44K se 

Format: v$ = SPACE$(n) 
Remarks: 7 must be in the range O to 32,767. 

See also ““SPC Function.” 
Example: This example uses the SPACE$ function to print 
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each number I on a line preceded by I spaces. An 
additional space is inserted because BASIC puts a 
space in front of positive numbers. 


PO FOR I =:1. 70-5 
20 X$ = SPACE$(I) 
30 PRINT X$;1 

40 NEXT I 


Results: 


' 


w Purpose: 


Versions: 


Format: 


Remarks: 


‘oe Example: 


SPC 


Function 


Skips n spaces in a PRINT statement. 


Cartridge Disk Advanced Compiler 


2 KK ** KOK 7 KK * KOK 


PRINT SPC(n) 

n must be in the range O to 255. 

If n is greater than the defined width of the device, 
the value used is n MOD width. SPC can be used 
only with PRINT, LPRINT, and PRINT # 
statements. 


See also ““SSPACE$ Function.’’ 


This example prints OVER and THERE separated 
by 15 spaces. 


PRINT “OVER” SPC(25)° “THERE 


Results: 


OVER THERE 
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SOR 


Function 
Purpose: Returns the square root of x. 
Versions: Cartridge Disk Advanced Compiler 

se ee se se 
Format: =v = SQR(x) 
Remarks: x must be greater than or equal to zero. 
Example: This example calculates the square roots of the 
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numbers 10, 15, 20, and 25. 


RP hi 1 0. 25. STEP. 5 
20 PRINT X, SQR(X) 


30 NEXT 

Results: 
10 3.162278 
15 3.872984 
20 4.472136 
25 5 


Y Purpose: 


Versions: 


Format: 


Remarks: 


STATIC 
Statement 


Designates simple variables or arrays as local to the 
subprogram in which they are declared and preserves 
their values when the subprogram is exited and 
reentered. 


Cartridge Disk Advanced Compiler 


OK 


STATIC variable|(n)][, variable|(n)]]... 


variable is a simple variable or array. An array 
declaration consists of a variable symbol 
followed by an integer constant in 
parentheses. The integer constant n 
represents the number of dimensions in 
the array, not the actual value of the 
dimensions. 


The STATIC statement may appear only inside a 
named subprogram (see the “‘SUB/END SUB 
Statement’’). If STATIC appears outside a named 
subprogram, an error occurs. 


Simple variables and arrays referenced or declared in 
subprograms are local to the subprograms in which 
they are declared. Initial values of zero or null string 
are assumed; however, if the subprogram is exited 
and reentered, the values retained for the variables 
may have been changed. Declaring the variables in a 
STATIC statement guarantees that the previous 
values are retained. 
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STATIC 
Statement 


Example: 


410 


If the first reference to an array is made with the 

STATIC statement, that array is allocated 

dynamically. Such arrays are not actually allocated “a 
until they are dimensioned with the DIM statement, 

or are redimensioned with the REDIM statement. 


Simple variables or arrays declared within a STATIC 
statement override any shared variables or arrays 
with the same name. 


By default, variables used in functions are global. 
The STATIC statement can also be used inside 
multiline function definitions to declare a variable as 
local to that function only. 


For related information, see the ““SHARED 
Statement.”’ 


The following program computes the factorial value A 
of a number. 


200 REM FACTORIAL PROGRAM 

210 DIM SHARED NFACT, N 

220 INPUT "ENTER NUMERAL"; M 

230 N=M 

240 WHILE N > 1 

250 = CALL FACTORIAL 

260° Ne Ste 

270 WEND 

280 PRINT M;" FACTORIAL = ";NFACT 
290 END 

300 REM **** FACTORIAL SUBPROGRAM **** 
310 SUB FACTORIAL STATIC 

320 STATIC Nl 

330 REM N1 WILL RETAIN ITS VALUE 
340 REM AFTER SUBPROGRAM IS EXITED 


350 IF N1 <> O THEN N1 = N1 * N ELSE N1 = N - 
360 IF N = 2 THEN NFACT = NI 
370 END SUB 


STICK 
Function 


& Purpose: Returns the x and y coordinates of two joysticks. 


Versions: Cartridge Disk Advanced Compiler 
* ok ** OK * OK * KK 


Format: v = STICK(n) 
Remarks: 


n is a numeric expression in the range O to 3 
that affects the result as follows: 


0 returns the x coordinate for joystick A. 
t returns the y coordinate of joystick A. 
Z returns the x coordinate of joystick B. 
3 returns the y coordinate of joystick B. 


Note: STICK(0O) contains all four values for the 
coordinates. To use any of the other stick 
functions (STICK(1), STICK(2) or STICK(3)), 
you must first call STICK(0O). 


The range of values for x and y depends on your 
particular joysticks. 
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STICK 
Function 


Example: This program prints 100 samples of the coordinates 
of joystick B. 


10 PRINT “Joystick B" ‘9 


20 PRINT "x coordinate','"y coordinate’ 
30 FOR J=1 TO 100 

40 TEMP=STICK(Q) 

5@ X=STICK(2): Y=STICK(3) 

60 PRINT X,Y 

70 NEXT 
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v Purpose: 


Versions: 


Format: 


Remarks: 


STOP 
Statement 


Stops execution of a program and returns to 
command level. 


Cartridge Disk Advanced Compiler 


OK * OK * OK * K 


STOP 


STOP statements can be used anywhere in a program 
to stop execution. When BASIC encounters a STOP 
statement, it displays the following message: 


STOP in Line xxx of Module Modulename At Address ---:--- 


Hit any key to return to system 


When the compiler encounters a STOP statement, it 
displays a message with a hexadecimal address 
indicating where the program stopped. If you 
compile using the /D, /X, or /E switch, the compiler 
displays the line number of the stopping point 
instead of the hexadecimal address. 


STOP closes all open files. 
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STOP 
Statement 


Example: This example calculates the value of TEMP, then 


stops. While the program is stopped, you can check 
the value of TEMP. 


19 INPUT A, B 


20 TEMP= A*B 

3Q@ STOP 

40 FINAL = TEMP+20@: PRINT FINAL 
Results: 

jee ee a 


STOP in Line xxx of Module Modulename At Address ---:--- 


Hit any key to return to system 
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w Purpose: 


Versions: 


Format: 


Remarks: 


Example: 


STRS$ 
Function 


Returns a string representation of the value of x. 


Cartridge Disk Advanced Compiler 


* KK * Kk 2K * KK 


v$ = STRS$(x) 
x iS any numeric expression. 


If x is positive, the string returned by STR$ contains 
a leading blank (the space reserved for the plus sign). 
For example: 


PRINT STR$(321); LEN(STR$(321) ) 


Results: 


321 4 


The VAL function is complementary to STR$. See 
the “VAL Function.” 


This example branches to different sections of the 
program according to the number of digits in a 
number that is entered. The number of digits is 
counted by using STR$ to convert the number to a 
string; then the program branches, based on the 
length of the string. 


10 INPUT "TYPE A NUMBER" ;N 
20 ON LEN(STR$(N))-1 GOSUB 30,100,200 ,300 
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STRIG 
Statement and Function 


Purpose: Returns the status of the joystick buttons (triggers). 


Versions: Cartridge Disk Advanced Compiler 
* * ok ** K 


Format: As a statement: 
STRIG ON 


STRIG OFF 


As a function: 


v = STRIG(n) 


Remarks: “a 


n iS a Numeric expression in the range O to 7. It 
affects the value returned by the function as 
follows: 


0 Returns -1 if button Al was pressed 
since the last STRIG(O) function call; 
returns O if not. 


1 Returns -1 if button A1 is currently 
pressed; returns O if not. 


zZ Returns -1 if button B1 was pressed 
since the last STRIG(2) function call; 
returns O if not. 


3 Returns -1 if button B1 is currently 
pressed; returns O if not. 
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STRIG 
Statement and Function 


4 Returns -1 if button A2 was pressed 
since the last STRIG(4) function call; 
returns O if not. 


5 Returns -1 if button A2 is currently 
pressed; returns O if not. 


6 Returns -1 if button B2 was pressed 
since the last STRIG(6) function call; 
returns Q if not. 


7 Returns -1 if button B2 is currently 
pressed; returns O if not. 


STRIG ON must be executed before any STRIG(n) 
function calls can be made. After STRIG ON, every 
time the program starts a new statement, the 
compiler checks to see if a button was pressed. 


If STRIG is OFF, no testing takes place. 


See the next entry, “STRIG(n) Statement,” for 
enhancements to the STRIG function. 
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STRIG(n) 
Statement 


Purpose: — Enables and disables trapping of the joystick 
buttons. 


Versions: Cartridge Disk Advanced Compiler 
* kK ** K * OK 


Format: STRIG(n) ON 
STRIG(n) OFF 
STRIG(n) STOP 
Remarks: 


n can be 0, 2, 4, or 6 and indicates the button to 
be trapped as follows: 


button Al 
button Bl “& 
button A2 


button B2 


Ahn © 


STRIG(n) ON must be executed to enable trapping 
by the ON STRIG(n) statement. See the “ON 
STRIG Statement.’ After STRIG(n) ON, every time 
the program starts a new statement, the compiler 
checks to see if the specified button has been 
pressed. 


If STRIG(n) OFF is executed, no testing or trapping 
takes place. Even if the button is pressed, the event 
is not remembered. 


If a STRIG(n) STOP statement is executed, no 
trapping takes place. However, if the button is “ 
pressed it is remembered so that an immediate trap 
takes place when STRIG(n) ON is executed. 
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o Purpose: 


Versions: 


Format: 


Remarks: 


‘oe Examples: 


STRINGS 
Function 


Returns a string length n whose characters all have 
ASCII code m or the first character of x$. 


Cartridge Disk Advanced Compiler 


* KK OK * *K * OK 


v$ = STRINGS$(n,m) 


v$ = STRING$(n,x$) 


n,m_ are in the range 0 to 32767. 
x$ is any string expression. 


This example repeats an ASCII value of 45 to print a 
string of hyphens. 


10 X$ = STRING$(10,45) 
20 PRINT X$ "MONTHLY REPORT" X$ 


Results: 
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STRINGS 
Function 


This example repeats the first character of the string 
“ABCD”. 


10 X$="ABCD" ‘y 


20 Y$=STRINGS$(10,X$) 
30 PRINT Y$ 


Results: 


AAAAAAAAAA 
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SUB and END SUB and EXIT SUB 


VY Purpose: 


Versions: 


Format: 


Y Remarks: 


Statement 


Marks the beginning and end of an subprogram. 


Cartridge Disk Advanced Compiler 


* KOK 


SUB global name |(formal parameter list)| STATIC 
[EXIT SUB] 
END SUB 


global name is a variable name up to 31 characters 
long. This name cannot appear in any 
other SUB statement. 


formal parameter list 
can contain simple variables and arrays. 
Parameters in the list are separated by 
commas. Arrays must be declared as 
follows: 


array(number of dimensions) 


array is the name chosen for the 
array 
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SUB and END SUB and EXIT SUB 
Statement 


number of dimensions 
is an integer constant 
indicating the number of fo) 
dimensions in the array. 
Note that the actual 
dimensions are not given 
here, only a number 
indicating how many 
dimensions are being used. 


STATIC indicates that the subprogram is 
nonrecursive; that is, it does not contain 
an instruction that calls itself or that 
calls a program that in turn calls the 
original subprogram. Only nonrecursive 
programs are supported; therefore, a 
warning (ST) error is generated if 
STATIC is omitted. 


A subprogram is similar to a multiline function. “& 
However, unlike a multiline function, a subprogram 

does not return a value associated with its name, and 
therefore cannot appear as part of an expression. 


Another difference is that the formal parameter list 
used by subprograms offers more flexibility than the 
formal parameter list in a multiline function. In 
subprograms, the formal parameters are called by 
name, and arrays can be passed to other programs. 


Subprograms are delimited by the SUB and END 
SUB statements. A subprogram must begin with a 
SUB statement and end with an END SUB 
statement. The EXIT SUB statement is used to exit 
a subprogram before the END SUB statement is 
executed. Execution of an EXIT SUB or END SUB 
statement transfers program control back to the 
calling routine. 
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SUB and END SUB and EXIT SUB 
Statement 


Subprograms are referenced by the CALL statement 
with a parameter list. When the subprogram is exited 

eS and reentered, the value that is retained fora 
variable may be affected by another portion of your 
program. To guarantee that the variable retains its 
assigned value upon reentry to the subprogram, it 
should be declared as STATIC. See “‘Calling 
Assembly Language Subroutines” under ‘‘Modular 
Programming” in BASIC Compiler 2.00 
Fundamentals for more information. 


Any simple variables or arrays referenced in the 
subprogram are considered to be local unless they 
have been explicitly declared to be SHARED 
variables. 


See also “CALL Statement,” “SHARED 
Statement,” and “STATIC Statement” and 

Y “Modular Programming” in BASIC Compiler 2.00 
Fundamentals. 
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SUB and END SUB and EXIT SUB 
Statement 


Example: This program contains two subprograms. One 
subprogram converts all characters of a string to 
uppercase; the other subprogram converts all 
characters of a string to lowercase. 


220 A$="abcdel2345ABCDE! @#$%" 

230 CALL upper(A$,B$) 

240 CALL lower(A$,C$) 

250 IF B$="ABCDE12345ABCDE! @#$%" __ 
AND C$="abcdel2345abcde! @#$%" THEN 279 

260 PRINT "FAILED" 

270 END 

280 SUB upper(N$,R$) STATIC 

290 LCASELET$="abcdefghijk lmnoparstuvwxyz" 

300 UCASELET$="ABCDEFGHIJKLMNOPQRSTUVWXYZ" 

310 L=LEN(N$) 

320 IF L=@ THEN upper$="":EXIT SUB 

330 FOR I = 1 TOL 

340 P=INSTR(LCASELET$ ,MID$(N$,1I,1)) 

350 IF P <> @ THEN N$=MID$(N$,1,I-1)_ 
+MID$(UCASELET$,P,1)+MID$(N$,I+1,L-I+1) 

360 NEXT 

370 R$=N$ 

389 END SUB 

39% SUB lower(N$,R$) STATIC 

400 LCASELET$="abcdefghijkImnopqrstuvwxyz- 

41Q@ UCASELET$="ABCDEFGHIJKLMNOPQRSTUVWXYZ" 

420 L=LEN(N$) 

430 IF L=@ THEN lower$="":EXIT SUB 

449 FOR I =1 TOL 

450 P=INSTR(UCASELET$ ,MID$(N$,1I,1)) 

460 IF P <> @ THEN N$=MID$(N$,1,I-1)_ 
+MID$(LCASELET$,P,1)+MID$(N$,I+1,L-I+1) 

47@ NEXT 

480 R$=N$ 

490 END SUB 
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Y& Purpose: 


Versions: 


Format: 


Remarks: 


Example: 


SW AP 
Statement 


Exchanges the values of two variables. 


Cartridge Disk Advanced Compiler 


* KK * KOK * KK * KK 


SWAP variablel, variable2 


variablel, variable2 
are the names of two variables or array 
elements. 


Any type variable can be swapped (integer, 
single-precision, double-precision, string), but the 
two variables must be of the same type or a Type 
mismatch error results. 


In this example, after line 30 is executed, A$ has the 
value “ ALL ” and B$ has the value “ ONE .” 


10 A$=" ONE " : B$=" ALL " : C$="FOR" 
20 PRINT A$;C$;B$ 


30 SWAP A$, B$ 
40 PRINT A$;C$5B$ 


Results: 


ONE FOR ALL 
ALL FOR ONE 
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SYSTEM 
Command 


Purpose: — Exits your compiled program and returns to DOS. 


Versions: Cartridge Disk Advanced Compiler 
** K KK ** KK * KOK 


Format: SYSTEM 


Remarks: SYSTEM closes all files and returns to DOS. 
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we Purpose: 


Versions: 


Format: 


Remarks: 


TAB 
Function 


Tabs to position n. 


Cartridge Disk Advanced Compiler 


* KK * KK AK * RK 


PRINT TAB(n) 
n must be in the range 1 to 255. 


If the current print position is already beyond space 
n, TAB goes to position n on the next line. Space 1 
is the leftmost position and defined WIDTH is the 
rightmost position. 


TAB can be used only in PRINT, LPRINT, and 
PRINT # statements. 


If the TAB function is at the end of the list of data 
items, BASIC does not add a carriage return, as 
though the TAB function had an implied semicolon 
after it. 
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TAB 


Function 
Example: TAB is used in the following example to cause the 
information on the screen to line up in columns. “ 


18 PRINT "ITEM" TAB(25) "AMOUNT" : PRINT 
2@ READ A$,B$ 

38 PRINT A$ TAB(25) B$ 

40 DATA "GROCERIES" ,"$25.9@" 


Results: 
ITEM AMOUNT 
GROCERIES $25.00 
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‘we Purpose: 


Versions: 


Format: 


Remarks: 


Example: 


TAN 
Function 


Returns the trigonometric tangent of x. 


Cartridge Disk Advanced Compiler 


** K * * ** KK 
v= TAN(x) 
x is the angle in radians. To convert degrees to 
radians, multiply by PI/180, where 
PI=3.141593. 


This example calculates the tangent of 45 degrees. 
10 PI=3.141593 

20 DEGREES=45 

30 PRINT TAN(DEGREES*PI/18@) 


Results: 


] 
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TIMES 
Variable and Statement 


Purpose: _ Sets or retrieves the current time. ‘> 


Versions: Cartridge Disk Advanced Compiler 
* kK 2 2 2k 2k kK 


Format: As a variable: 
vs = TIME$ 
As a statement: 
TIMES = xs 
Remarks: _ For the variable (v§ = TIME$): 


The current time is returned as an 8-character string. 
The string is of the form hh:mm:ss, where hh is the “ 
hour (00 to 23), mm is the minutes (00 to 59), and ss 

is the seconds (00 to 59). (You may have set the 

time in DOS before you invoked your program.) 


For the statement (TIMES = x$): 
The current time is set. x§$ is a string expression 


indicating the time to be set. x$ can be given in one 
of the following forms: 


hh Set the hour in the range O to 23. 
Minutes and seconds default to OO. 

hh:mm Set the hour and minutes. Minutes must 
be in the range 0 to 59. Seconds default 
to OO. 


hh:mm:ss Set the hour, minutes, and seconds. 
Seconds must be in the range 0 to 59. 
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Example: 


TIMES 
Variable and Statement 


A leading zero can be omitted from any of the above 
values, but you must include at least one digit. For 
example, if you want to set the time as a half hour 
after midnight, you can enter: 


TIME$ =‘‘0:30”’ 
but not 
TIME$ =‘“‘:30”’ 


If any of the values are out of range, an Illegal 
function call error is issued. The previous time is 
retained. If x§$ is not a valid string, a Type mismatch 
error results. 


The following program continuously displays the 
time on the screen. 


EO-CLS 

20 LOCATE 10,15 
30 PRINT TIMES 
40 GOTO 290 
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TIMER 
Function and Statement 


Purpose: Returns a single-precision number representing the ‘> 
number of seconds elapsed since midnight or a 
system reset. 


Versions: Cartridge Disk Advanced Compiler 


Format: 
As a Function: v= TIMER 
As a Statement: 
TIMER ON 


TIMER OFF 


TIMER STOP “ 


Remarks: Fractional seconds are calculated to the nearest 
degree possible. TIMER is a read-only function. 


Example: This example illustrates how TIMER resets after 
midnight. Values may be slightly different for your 
system. 


10 TIME$="23:59:59" 

20 FOR I=1 TO 20 

39 PRINT "TIME$= ";TIME$;" TIMER=";TIMER 
40 NEXT 
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Results: 


TIME$= 
TIME $= 
TIME $= 


TIME$= 
TIME $= 
TIME $= 
TIME$= 


es. 
ie Be 
ae 


pas 
00: 
QQ: 
OO: 


TIMER 


Function and Statement 


TIMER= 86399.96 
TIMER= 86399.11 
TIMER= 86399.18 


TIMER= @ 

TIMER= .@5 
TIMER= .16 
TIMER= .21 


433 


TRON and TROFF 
Commands 


Purpose: Traces the execution of program statements. ‘> 


Versions: Cartridge Disk Advanced Compiler 
* KK * KK KK KK 


Format: TRON 
TROFF 


Remarks: As an aid in debugging, the TRON command enables 
a trace flag that prints each line number of the 
program as it is executed. The numbers appear 
enclosed in square brackets. 


If line numbers are only used occasionally in your 
program, and you compiled using the /N parameter, 

the values printed by TRON are the last known line -) 
numbers. The trace is turned off by the TROFF 

command. 


Note: When debugging your program with 
TRON and TROFF , you must compile using 
the /D switch. This switch causes the compiler 
to perform more extensive error checking, and 
detects errors such as RETURN without 
GOSUB, and Subscript out of range, that 
normally go undetected. 
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Example: 


TRON and TROFF 
Commands 


This example uses TRON and TROFF to trace 
execution of a loop. The numbers in brackets are 
line numbers; the numbers not in brackets at the end 
of each line are the values of J, K, and L, which are 
printed by the program. 


10 K=1@ 

20 FOR I=1 TO 2 
30 L=K + 10 

40 PRINT J3;K3L 
50 K=K+19@ 

6Q@ NEXT 

7@ END 


Results: 
LIM@IL2Z0IL30)140] 0 10 20 


L5@IL6GIL3GIL40) 0 20 39 
[5d Il69IL70) 
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UBOUND 
Function 


Purpose: 


Versions: 


Format: 


Remarks: 
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Returns the upper bound of the specified dimension ‘y 
of an array. 


Cartridge Disk Advanced Compiler 


* K 
UBOUND (array,[dim]) 
array is the name of the array being examined. 
dim is an integer constant from 1 to the 


number of dimensions in the array. The 
default value is 1. 


UBOUND returns the upper bound of the specified “& 
dimension of an array. | 


LBOUND and UBOUND are particularly useful for 
determining the size of an array passed to a 
subprogram. 


Example: 


UBOUND 
Function 


The following example uses LBOUND and 
UBOUND to determine the size of the array to be 
sorted. 


200 OPTION BASE 1 

219 DIM SHARED A(1Q) 

22% CLS 

230 PRINT "THE UNSORTED ARRAY" 

240 FOR I = LBOUND(A) TO UBOUND(A) 
250 READ A(1) 

260 PRINT A(I) 

270 NEXT I 

280 CALL SORT 

290 PRINT "THE SORTED ARRAY" 

300 FOR I = LBOUND(A) TO UBOUND(A) 
310 PRINT A(T) 

320 NEXT I 

3308 DATA 40, 100, 19, 8, 66, 23 

340 DATA 83, 6, 54, 120, 25, 98 

358 END 

360 REM **** EXCHANGE SORT SUBPROGRAM **** 
37% SUB SORT STATIC 

380 STATIC B 

398 REM USE LBOUND TO DETERMINE LOWER 
400 REM BOUNDARY OF ARRAY 

419 FOR I = LBOUND(A) TO UBOUND(A) - 1 
420 FOR J = I + 1 TO UBOUND(A) 


430 IF A(I) <= A(J) THEN 479 
440 B = A(J) 

450 A(J) = ACI) 

460 A(I) = 8 

470 NEXT J 

480 NEXT I 

499 END SUB 
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UNLOCK 


Statement 
Purpose: Releases locks applied to an opened file. ‘y 
Versions: Cartridge Disk Advanced Compiler 


Format: 


Remarks: 
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KK 


Not valid for DOS versions earlier than 3.00. 


UNLOCK [#]n [, [recnum | [TO recnum|| 


n is the number of the opened file. 


recnum _ is the record number used to specify a 
range of records to be unlocked. 


Executing an UNLOCK statement with a DOS “4 
version earlier than 3.00 produces a runtime error. 3 


Before you run an application that uses any LOCK 
or UNLOCK statements, you must first install the 
SHARE module in memory. This module is on the 
DOS disk and is installed by entering the command 
“SHARE” at the DOS prompt. 


If a record number or range of record numbers is 
specified, and the file is opened in random mode, 
only those records in the range are unlocked. The 
record number range must exactly match the record 
number range given in the LOCK statement, or a 
Permission denied error occurs. 


Failure to unlock all locks on a file before closing the “ 
file or exiting the program may cause undefined F 
results. 


YY Examples: 


UNLOCK 


Statement 
The range of legal record numbers is | to 16775616. 
The following UNLOCK is legal: 
LOCK #1,1 TO 4 
LOCK #1,5 T0 8 
UNLOCK #!,1 T0 4 
UNLOCK #1,5 T0 8 


However, the following UNLOCK Is illegal: 


LOCK #1,1 T0 4 
LOCK #1,5 10 8 
UNLOCK #1,1 T0 8 


USR 


Function 


Purpose: 


Versions: 


Format: 


Remarks: 
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Calls a machine language subroutine that was defined 
by DEF USR. 


Cartridge Disk Advanced Compiler 
sek skekeok sok 2k soko 


vy = USRIn|(x) 


n is an integer in the range O-9 and 
corresponds to the digit supplied with the 
DEF USR statement for the desired 
routine. If 7 is omitted, USRO is 
assumed. See the “‘DEF USR 
Statement.” 


x is adummy argument. Use any value. 


Although the USR function is implemented in the 
compiler to call machine language subroutines, there 
is NO way to pass parameters to the subroutine, 
except through the use of POKEs to memory 
locations that are later accessed by the machine 
language routine. That is, x is a dummy argument. 


As with the interpreter, the starting address of the 
subroutine is determined by the addresses given in 
the DEF SEG and DEF USR statements. The DEF 
USR statement specifies the address as an offset into 
the current segment specified by the last DEF SEG 
statement executed. 


The USR function returns the integer result in the 
BX register. 


USR 
Function 


The machine language subroutine may be loaded into 
memory, as it was in the interpreter, using a BLOAD 
command. See the “CALL ABSOLUTE Statement” 
for more information. 


The subroutine is a FAR procedure, so the return to 
your application must be by an intersegment RET 
instruction. However, note that since the compiler 
allows strings to be up to 32767 bytes long, the 
string descriptor requires four bytes rather than three 
(low byte, high byte of length, followed by low byte, 
high byte of the address). If your machine language 
routine uses string arguments, you may need to 
recode it to take this difference into account. 


If you have the IBM Personal Computer Macro 
Assembler, it is probably easier to assemble your 
subroutines and then link them directly to the 
compiled program. Then you can use the CALL 
statement to reference the routine. CALL does not 
require the segment and offset values to be identified 
in your application program—the Linker 
automatically takes care of that for you. 
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USR 
Function 


Example: This example loads an assembly language subroutine 
into an integer array. The vn in line 60 is determined 
by the the total number of bytes in the subroutine ‘> 
divided by 2. 


1@ OPTION BASE 1 

20 DEFINT A-Z 

50 ‘Dimension array for subroutine 

6@ DIM ARRAY (n) 

70 ‘Obtain offset of 1st array element 
80 SUBRT = VARPTR(ARRAY(1)) 

9% ‘Load routine into the integer array 
190 BLOAD "ASMFILE" ,SUBRT 


1000 ‘Pass offset to DEF USR 
191@ DEF USR@ = SUBRT 

1020 ‘Execute the subroutine 
1030 J = USRQ@(I) 
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& Purpose: 


Versions: 


Format: 


Remarks: 


Example: 


VAL 
Function 


Returns the numerical value of string x§. 


Cartridge Disk Advanced Compiler 


OK OK * K ** KO 


v= VAL(x3) 
x$ is a string expression. 


The VAL function strips blanks, tabs, and line feeds 
from the argument string to determine the result. 
For example, 


VAL ( i -3 it ) 
Results: 
=3.. 


If the first characters of x$ are not numeric, 
VAL(x$) returns O (zero). 


See the “STR$ Function’”’ for numeric to string 
conversion. 


In this example, VAL is used to extract the house 
number from an address. 


PRINT VAL("34@8 SHERWOOD BLVD.") 
Results: 


3408 
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VARPTR 
Function 


Purpose: Returns the offset to the current data segment of 
memory of the variable. 


Versions: Cartridge Disk Advanced Compiler 
* K ** KK ** OK ** KK 


Format: vy = VARPTR (variable) 
Remarks: 


variable is the name of a numeric or string 
variable or array element in your 
program. A value must be assigned to 
variable before the call to VARPTR, or 
an Illegal function call error results. 


VARPTR returns an offset in the range 0 to 65535. “ 
This number is the offset into the compiler’s data 

segment of the first byte of data identified with 

variable. The format of this data is described under 

‘How Variables Are Stored” in BASIC Compiler 

2.00 Fundamentals. 


VARPTR with a dynamic numeric array as an 
argument returns a full 20-bit address in 
single-precision format. 
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Example: 


VARPTR 
Function 


Note: 

All of these statements use 20-bit 
single-precision offsets as returned by 
VARPTR: 


For compatibility with previous versions of the 
compiler and interpreter, VARPTR returns a 
2-byte offset into the current segment if 
assigned to an integer. 


This example uses VARPTR to get the data from a 
variable. In line 30, P gets the address of the data. 
Integer data is stored in two bytes, with the less 
significant byte first. The actual value stored at 
location P is calculated in line 40. The bytes are read 
with the PEEK function, and the second byte is 
multiplied by 256 because it contains the high-order 
bits. 


19 DEFINT A-Z 

20 DATA1=50@ 

3Q@ P=VARPTR(DATA1) 

4Q V=PEEK(P) + 256*PEEK(P+1) 
5Q@ PRINT V 
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VARPTRS Function 


Purpose: Returns a character form of the offset of a variable 
in memory. 


Versions: Cartridge Disk Advanced Compiler 


Format: v$ = VARPTR$(variable) 
Remarks: 


variable is the name of a variable in the program. 


VARPTR$ returns a 3-byte string in the form: 


low byte of high byte of 


variable address variable address 


type indicates the variable type: 


integer 

string 
single-precision 
double-precision 


CoOh WN 
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VARPTRS Function 


The returned value is the same as: 
CHR$(type)+MKI$(VARPTR( variable) ) 

You must use VARPTRS to indicate a variable 
name in the command string for PLAY or DRAW. 
For example: 


Interpreter Method 


PLAY "XA$;" 
PLAY "Ge!;" 


Compiler Method 


PLAY "X"+VARPTR$(A$) 
PLAY "O="+VARPTR$(I) 
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VIEW 


Statement 


Purpose: 


Versions: 


Format: 


Remarks: 


44 


Defines a rectangular subset of the screen onto 
which WINDOW and WINDOW contents are 


mapped. 


Cartridge 


* kK 


Disk Advanced Compiler 


6 OK KK 


Graphics mode only. 


VIEW [ [SCREEN] (xJ,yJ)- (x2,y2) [,[attribute | 
| ,[ boundary]]] 


SCREEN 


If the SCREEN argument is included, 
all points plotted are absolute and can 
be inside or outside the screen limits. 
However, only those points within the 
viewport limits are visible. For example 
if: 


19 VIEW SCREEN (10,10)-(200,100) 


is executed, the point plotted by PSET 
(0,0),3 does not appear on the screen 
because 0,0 is outside the viewport. 
PSET (10,10),3 is within the viewport 
and places the point in the upper-left 
corner. 


If the SCREEN argument is omitted, all 
points plotted are relative to the 
viewport. That is, x/ and y/ are added 
to the x and y coordinates before 
plotting the point on the screen. For 
example, if: 


VIEW 
Statement 
10 VIEW (10,10)-(200,190) 


is executed, the point plotted by PSET 
(0,0),3 is at the screen location 10,10. 


(x1,y1)-(x2,y2) 


attribute 


are the upper-left (x/,y/) and the 
lower-right (x2,y2) coordinates of the 
viewport defined. The x and y 
coordinates must be within the limits of 
the screen or an Illegal function call 
error occurs. For more information, see 
“Specifying Coordinates”’ under 
‘““Graphics Modes” in BASIC Compiler 
2.00 Fundamentals. 


lets you fill the defined viewport with 
color. If attribute is omitted, the 
viewport is not filled. attribute is an 
integer expression that chooses an 
attribute from the attribute range for 
the current screen mode. In SCREEN 
1, (medium resolution), attribute can 
range from 0 to 3. In SCREEN 2, (high 
resolution), attribute can be O or 1. 


The default color attribute for the 
foreground is the maximum color 


attribute for that screen mode. 


The default color attribute for the 
background is always zero. 
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VIEW 


Statement 


450 


boundary 


lets you draw a boundary line around the 
viewport (if space is available). If 
boundary is omitted, no boundary is 
drawn. boundary is an integer expression 
in the range described in color. 


VIEW 
Statement 


It is important to note that VIEW sorts the x and y 
argument pairs, placing the smaller values for x and y 
first. For example: 


VIEW (190,100)-(5,5) 
becomes: 

VIEW (5,5)-(100,100) 
Another example: 

VIEW (318,190)-(200,159) 
becomes: 

VIEW (200,100)-(310,15@) 


All possible pairings of x and y are valid. The only 
restriction is that x/ cannot equal x2 and y/ cannot 
equal y2. The viewport cannot be larger than the 
screen. 


VIEW with no arguments defines the entire screen as 
the viewport. 


You can define multiple viewports, but only one 
viewport can be active at a time. RUN and changes 
in SCREEN attributes disable the viewports. 


VIEW used with WINDOW allows you to scale 
images. See the second example. See also 
“WINDOW Statement.” 


Note: When VIEW is used, the CLS statement 
clears only the current viewport. To clear the 
entire screen, you must use VIEW to disable the 
viewports, and then use CLS to clear the screen. 
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VIEW 
Statement 


Examples: The following example defines four viewports: 


1@ SCREEN 1:VIEW:CLS:KEY OFF 
30 VIEW -6165:,7)-1315,91).,.,2 
AQ: VIEW CL. 105)-(151 ,195) , 2 
50 VIEW (165.705) =-(315,195)..1 
6@ LOCATE 2,4:PRINT "Viewport 1" 
7@ LOCATE 2,25:PRINT "Viewport 2" 
80 LOCATE 15,4:PRINT "Viewport 3" 
92 LOCATE 15,25:PRINT "Viewport 4" 
1090 VIEW (1,1)-(151,91):GOSUB 1000 
200 VIEW (165,1)-(315,91):GOSUB 2000 
300 VIEW (1,105)-(151,195):GOSUB 3000 
400 VIEW (165,105)-(315,195):GOSUB 4900 
990 END 
1000 CIRCLE (65,50) ,30,2 
1910 ‘Draw a circle in first viewport 
1920 RETURN 
2000 LINE (45,50)-(90,75),1,B 
2019 ‘Draw a box in second viewport a. 
2020 RETURN 
3000 FOR D=@ TO 360:_ 
DRAW "ta="+VARPTR$(d)+'nu2@":NEXT 
3010 ‘Draw spokes in third viewport 
3020 RETURN 
4000 PSET(6@,50),2:DRAW "e15;f153;13Q0" 
4910 ‘Draw a triangle in fourth viewport 
4920 RETURN 


This example demonstrates scaling with VIEW. 


19 KEY OFF:CLS:SCREEN 1,@:COLOR 9,0 

20 WINDOW SCREEN(320,0)-(0,200) 

38 GOTO 89 

40 C=1 

5@ CIRCLE (160,190) ,69,C,,,5/18 

68 CIRCLE (160,190) ,60,C,,,1 

7Q@ RETURN “ 
88 GOSUB 4@:FOR I=1 TO 15@@:NEXT I:CLS 

90 VIEW (1,1)-(168,99),,2:GOSUB 40 
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ww Purpose: 


Versions: 


Format: 


Remarks: 


WAIT 
Statement 


Suspends program execution while monitoring the 
Status of a machine input port. 


Cartridge Disk Advanced Compiler 


6 KK OK * 3K * KOK 


WAIT port, n|,m] 


port is the port number, in the range O to 65535. 
n,m _ are integer expressions in the range 0 to 255. 


See the IBM Personal Computer Technical Reference 
for a description of valid port numbers (I/O 
addresses). 


The WAIT statement suspends program execution 
until a specified machine input port develops a 
specified bit pattern. 


The data read at the port is XORed with the integer 
expression m and then ANDed with n. If the result is 
zero, BASIC loops back and reads the data at the 
port again. If the result is nonzero, execution 
continues with the next statement. If m is omitted, it 
is assumed to be zero. 
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WAIT 
Statement 


The WAIT statement lets you test one or more bit 
positions on an input port. You can test the bit 
position for either a 1 or a O. The bit positions to be 
tested are specified by setting 1’s in those positions 
in n. If you do not specify m, the input port bits are 
tested for 1’s. If you specify m, a 1 in any bit 
position in m (for which there is a 1 bit in n) causes 
WAIT to test for a O for that input bit. 


When executed, the WAIT statement loops, testing 
those input bits specified by 1’s in n. If any one of 
those bits is 1 (or O if the corresponding bit in m is 
1), the program continues with the next statement. 
Thus WAIT does not wait for an entire pattern of 
bits to appear, but only for one of them to occur. 


Note: It is possible to enter an infinite loop with 
the WAIT statement. You can do a Ctrl-Break 
or a System Reset to exit the loop. 


Example: This example waits for any key to be pressed. The 
key can still be read using any form of input (for 
example, INKEY$). 


190 WAIT &H60,&0 
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we Purpose: 


Versions: 


Format: 


WHILE and WEND 
Statements 


Executes a series of statements in a loop as long as a 
given condition is true. 


Cartridge Disk Advanced Compiler 


** OK * KOK KK * KOK 


WHILE expression 
(loop statements) 
WEND 


expression is any numeric expression. 


If expression is true (not zero), loop statements 
execute until the WEND statement is encountered. 
BASIC then returns to the WHILE statement and 
checks expression. If expression is still true, the 
process is repeated. If it is not true, execution 
resumes with the statement following the WEND 
statement. 


WHILE-WEND loops can be nested to any leve. 
Each WEND will match the most recent WHILE. 
An unmatched WHILE statement causes a WHILE 
without WEND error, and an unmatched WEND 
Statement causes a WEND without WHILE error. 
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WHILE and WEND 
Statements 


Example: 


456 


The following example sorts the elements of the 
array A into alphabetical order. A was defined with 
J elements. 


5 J=UBOUND(A,1) 
19 ‘bubble sort array A 
20 FLIPS=1 ‘force first pass thru loop 
3Q@ WHILE FLIPS 
40 FLIPS=@ 
5@ FOR I=1 TO J-l 
60 IF A(I)>A(I+1) THEN 
SWAP: ACI) AC I+1):.. FEIPS=1 
7Q@ NEXT I 
80 WEND 


& Purpose: 


Versions: 


Format: 


Remarks: 


WIDTH 
Statement 


Sets the output line width in number of characters. 
After outputting the indicated number of characters, 
BASIC adds a carriage return. 


Cartridge Disk Advanced Compiler 


* OK ** KO 7 OK * KK 


WIDTH size 
WIDTH device, size 


WIDTH #filenum, size 


size is a numeric expression in the range O to 
255. This is the new width. WIDTH 0 is 
the same as WIDTH 1. 


device is a string expression for the device 
identifier. Valid devices are SCRN;, 
LPT1:, bP Peer CoM: COM2:. 
or CASI1:. 


Note: The colons must be included as 
part of the device names. 


filenum is a numeric expression in the range 1 to 


127. This is the number of a file opened 
to an output device. 
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WIDTH 
Statement 


Depending on the device specified, the following 
actions are possible: 


WIDTH size or WIDTH “SCRN:”’ size 
Sets the screen width. Only 40- or 
80-column widths are allowed. WIDTH 
40 is not valid for the IBM Monochrome 
Display. 


If the screen is in medium-resolution 
graphics mode (as occurs with a SCREEN 
1 statement), WIDTH 80 forces the 
screen into high resolution (as with a 
SCREEN 2 statement). The reverse if 
true when in high resolution. 


Note: Changing the screen width 
causes the screen to be cleared, and 
sets the border screen color to black. 


WIDTH device, size 
Is a deferred width assignment for the 
device. This form of WIDTH stores the 
new width value without changing the 
current width setting. A subsequent 
OPEN to the device uses this value for 
width while the file is open. The width 
does not change immediately if the device 
is already open. 


LIST,‘““LPTn” do an implicit OPEN 
and are therefore affected by this 
statement. 


Note: LPRINT, LLIST, and ~ 
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WIDTH 
Statement 


WIDTH #filenum, size 
The width of the device associated with 
filenum is immediately changed to the new 
size specified. This allows the width to be 
changed at will while the file is open. 
This form of WIDTH has meaning only 
for LPT1: Note that the number sign (#) 
is required. 


Any value entered outside the ranges indicated 
results in an Illegal function call error. The previous 
value is retained. 


The width for each printer defaults to 80 when your 
program is started. The maximum width for the IBM 
Graphics Printer is 132. However, no error is 
returned for values between 132 and 255. 


It is up to you to set the appropriate physical width 
on your printer. Some printers are set by sending 
special codes; some have switches. For the IBM 
Graphics Printer you should use LPRINT 
CHR$(15); to change to a condensed type style 
when printing at widths greater than 80. Use 
LPRINT CHR$(18); to return to normal. The IBM 
Graphics Printer is set up to automatically add a 
carriage return if you exceed the maximum line 
length. 


Specifying a width of 255 disables line folding. This 
has the effect of ‘infinite’? width. WIDTH 255 is 
the default for communications files. 


Changing the width for a communications file does 
not change either the receive or the transmit buffer; 
it just causes a carriage return character to be sent 
after every size characters. 
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WIDTH 
Statement 
Changing screen mode affects screen width only 


when moving between SCREEN 2 and SCREEN 1 
or SCREEN 0. See the “SCREEN Statement.” 


Example: In this example, line 10 stores a printer width of 75 
characters per line. Line 20 opens file #1 to the 
printer and sets the width to 75 for subsequent 
PRINT #1,... statements. Line 6020 changes the 
current printer width to 40 characters per line. 
Notice that the WIDTH value must come before the 
OPEN statement. 


10 WIDTH LP ta” 75 
20 OPEN "LPT1:" FOR OUTPUT AS #1 


6920 WIDTH #1,40 


These examples change screen mode and width. -) 
SCREEN 1,@ ‘Set to med-res color graphics 

WIDTH 8@ ‘Go to hi-res graphics 

WIDTH 49 ‘Go back to medium res 

SCREEN @,1 ‘Go to 40x25 text color mode 

WIDTH 8@ ‘Go to 80x25 text color mode 
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WINDOW 
Statement 


& Purpose: Redefines the coordinates of the viewport. 


Versions: Cartridge Disk Advanced Compiler 
* ok * KK * K 


Graphics mode only. 
Format: WINDOW [ [SCREEN] (x/,y/)- (x2,y2) ] 
Remarks: 


SCREEN controls the orientation of the screen 
coordinate system. 


When SCREEN is omitted, the screen 
coordinates conform to the Cartesion 
coordinate system (x increases to the 
right, y increases upward.) 


When SCREEN is included, x increases 
to the right, and y increase downward. 


(x1,yl),(x2,y2) 
are programmer-defined coordinates 
called world coordinates. These 
coordinates are single-precision, 
floating-point numbers. They define the 
world coordinate space that is mapped 
into the the physical coordinate space, as 
defined by the VIEW statement. See the 
“VIEW Statement.”’ 
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WINDOW 
Statement 
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WINDOW allows you to draw objects in space 
(‘“‘world coordinate system’’) and not be bounded by 
the limits of the screen (‘“‘physical coordinate 
system’’). This is done by specifying the world 
coordinate pairs (x/,y/) and (x2,y2). BASIC then 
converts world coordinate pairs for subsequent 
display within the viewport. To make this 
transformation from world space to the physical 
space of the screen, BASIC must know what portion 
of the unbounded world coordinate space contains 
the information you want to be displayed. This 
rectangular region in the world coordinate space is 
called a window. 


In the physical coordinate system, if you run the 
following: 


SCREEN 2 


the screen appears with standard coordinates as: 


320,0 


y increases 


320,100 


$20;,199 639,199 


WINDOW 


Statement 
When the SCREEN attribute is omitted, the screen is 
viewed in true Cartesian coordinates. For example, 
given: 


WINDOW (-1,-1)-(1,1) 


the screen appears as: 


0,1 


y increases 


0,0 


y decreases 


Ued 


You may be familiar with this method of specifying 
coordinates. Because the Cartesian coordinate 
system is widely known, many people consider the 
coordinate system used with the graphics statements 
to be ''upside down.'' The SCREEN attribute allows 
you to select the coordinate system you are most 
comfortable with. 


Note that the y coordinate is inverted so that (x/,yJ1) 


is the lower-left coordinate and (x2,y2) is the 
upper-right coordinate. 
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WINDOW 
Statement 


When the SCREEN attribute is included, the 
coordinates are not inverted so that (x/,yJ) is the 


upper-left coordinate and (x2,y2) is the lower-right ‘y 
coordinate. For example: 


WINDOW SCREEN (-1,-1)-(1,1) 


defines the screen to look like this: 


0,-1 


y decreases 


0,0 


y increases 


G3 # 


It is important to note that WINDOW sorts the x and 
y argument pairs, placing the smaller values for x and 
y first. For example: 

WINDOW (100,100)-(5,5) 


becomes: 


WINDOW (5,5)-(100,100) 
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WINDOW 
Statement 
Another example: 
WINDOW (-4,4)-(4,-4) 


becomes: 


WINDOW (-4,-4)-(4,4) 


All possible pairings of x and y are valid. The only 
restrictions are that x/ cannot equal x2 and yl 
cannot equal y2. 


WINDOW also allows you to “‘zoom”’ and “‘pan.”’ 
Using a window with coordinates larger than an 
image displays the entire image, but the image is 
small and blank spaces appear on the sides of the 
screen. Choosing window coordinates smaller than 
an image forces clipping and allows only a portion of 
the image to be displayed and magnified. By 
specifying small and large window sizes, you can 
zoom in until an object occupies the entire screen, or 
you can zoom out until the image is just a spot on the 
screen. 


RUN, SCREEN, and WINDOW with no attributes 
disable any WINDOW definitions and return the 
screen to physical coordinates. 


Examples: The following example shows clipping using 
WINDOW. 


10 SCREEN 2:CLS 

20 WINDOW (-6,-6)-(6,6) 

39 CIRCLE (454) 633 

40 'the circle is large and only part is visible 


50 WINDOW (-100,-190)-(100,100) 
6@ CIRCLE (4,4),5,1 ‘the circle is very small 
7Q@ END 
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WINDOW 
Statement 


The following example shows the effect of zooming 


using WINDOW. a) 
Be KEY OF CES eSCecen 1,2 ' 
Ad) ae 
30 GOTO 16@ 
4Q _——— ee 
50 ‘procedure display 
60 ' 


70 LINE (X,@)-(-X,@),,,&HAA@@ ‘create x axis 
80 LINE (@,X)-(@,-X),,,&HAA@@ ‘create y axis 


100 CIRCLE (X%/2-X%72)..R ‘circlhe Has<redius + 
110 FOR P=1 TO 5@:NEXT P ‘delay loop 


129 

13Q@ RETURN 

AG ee eee 

50 = 

160 X=100@:WINDOW (-X,-X)-(X,X):R=2@ 

170 ‘create a graph with large coord range 

180 GOSUB 5@:FOR P=1 TO 10@@:NEXT P:CLS “ 
190 ° 


200 X=60:WINDOW (-X,-X)-(X,X):R=20 
210 ‘smaller coord range increase circle size 
220 GOSUB 5@:FOR P=1 TO 100@:NEXT P:CLS 


240 X=10@0:WINDOW (-X,-X)-(X,X):R=20 
250 ‘modify window to show only portion of axes 
260 GOSUB 5@:FOR P=1 TO 10@@:NEXT P:CLS 


280 PRINT ".... an example":PRINT" of zooming..° 
290 FOR P=1 TO 15@0:NEXT P 

308 CLS: T=-5@:U=10@: X=U 

31@ FOR I=1 TO 45 


320 T=T + 1:U=U - 1:X=X-1:R=20 

339 WINDOW (T,T)-(U,U):CLS:GOSUB 59 
340 NEXT I 

35% END 
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wv Purpose: 


Versions: 


Format: 


Remarks: 


WRITE 
Statement 


Outputs data to the screen. 


Cartridge Disk Advanced Compiler 


* KK 6 KK * KK * 


WRITE [list of expressions | 


list of expressions 
is a list of numeric and/or string 
expressions, separated by commas or 
semicolons. 


If the list of expressions is omitted, a blank line is 
displayed. If the list of expressions is included, the 
values of the expressions are displayed on the screen. 


When the values of the expressions are displayed, 
each item is separated from the one before it by a 
comma. Strings are delimited by quotation marks. 
After the last item in the list is printed, og program 
adds a carriage return/line feed. 


WRITE is similar to PRINT. The difference 
between WRITE and PRINT is that WRITE inserts 
commas between the items as they are displayed and 
delimits strings with quotation marks. Also, positive 
numbers are not preceded by blanks. 
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WRITE 
Statement 


Example: The following example shows how WRITE displays 
numeric and string values. ‘> 


19 A=80: B=90: C$=".THAT'S ALL" 
20 WRITE A,B,C$ 


Results: 


80,90,°.THAT'S ALL" 
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YY Purpose: 


Versions: 


Format: 


Remarks: 


WRITE# 
Statement 


Writes data to a sequential file. 


Cartridge Disk Advanced Compiler 


Xe 2 ok Xe 2 ok 2 2k ok 2 2 ok 


WRITE #filenum, list of expressions 


filenum is the number under which the file 
was opened for output. 


list of expressions 
is a list of string and/or numeric 
expressions, separated by commas or 
semicolons. 


The difference between WRITE # and PRINT # is 
that WRITE # inserts commas between the items as 
they are written and delimits strings with quotation 
marks. Therefore, it is not necessary for you to put 
explicit delimiters in the list. Also, WRITE # does 
not put a blank in front of a positive number. A 
carriage return/line feed sequence is inserted after 
the last item in the list is written. 
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WRITE# 
Statement 


Example: Let A$=‘‘..CAMERA” and B$=“‘.93604-1’’. The 
statement: 


WRITE #1,A$,B$ 


writes the following image to the file. 


". CAMERA" ," .93604-1" 
A subsequent INPUT # statement: 


INPUT #1,A$,B$ 
inputs “. CAMERA” to A$ and “*.93604-1” to BS. 
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Appendix A. Error Messages 


w During development of a BASIC program with the 
BASIC Compiler 2.00, two kinds of errors may occur: 


« BASIC Compiler 2.00 compiletime errors 
e BASIC runtime errors 


The BASIC Compiler 2.00 compiletime errors occur 
when you compile your program; the BASIC runtime 
errors only occur at the last step in the development 
process, when you actually run your compiled program. 
All these messages are listed in this appendix. 


The first part of this appendix lists error codes and 
messages for the errors detected by the BASIC 
Compiler 2.00. They are separated into two groups: 
prompt errors, that isssue a prompt describing the error, 
and usually allow you to correct the error and continue 
with the compiling process; and listing errors, that 
generally indicate an error in your program and appear 
in the compiler listing. 


Errors While Compiling a Program 


The error in this section occur when you are compiling 
a source file to produce an object module. 


Prompt Errors 


The following errors from the compiler are severe 
errors; that is, they must be corrected before you can 
continue. When they occur, the sequence of prompts to 
start the compiler is restarted, giving you a chance to 
correct the error. 


Message Meaning 


Bad filename 
You entered a file specification that was not 
properly formed. 


Enter the correct file specification. 


Bad switch: /z “ 


The character indicated by z is not a valid 
compiler parameter. 


Omit the parameter or enter the correct 
parameter. 


Can’t create file 
A compiler output file cannot be opened 
because there are no free directory entries on 
the diskette. 


If there are any files on the diskette that you 
don’t need, erase them; otherwise, use 
another diskette and retry the operation. 


Command error: ’2Z’ 
An error is in the command line at the 
character specified by z. 


Correct the command line. 


The following long messages are compilation error 
messages. When they occur, you must correct the 
problem and restart the compiler from the beginning. 


Message Meaning 


Binary source file 
The source file you specified to the compiler 
was not in ASCII format. 


Make sure you specified the right file. If 
necessary, start the interpreter, load the file, 
and save it again with the A option. 


Disk z full 
The diskette in the drive specified by z has no 
more disk storage space. If z is blank the 
drive is the DOS default drive. 


If there are any files on the diskette that you 
don’t need, erase them. Otherwise, use a 
new formatted diskette and retry the 
operation. 


File not found 
The source file you named does not exist on 
the drive specified. 


Check the file specification for the source 
file. If it is correct, insert the correct diskette 
and retry the operation. 


Internal Error 
An internal malfunction occurred in the 
BASIC Compiler 2.00. 


Recopy your compiler diskette. Check the 
hardware and retry the compile. If the error 
reoccurs, report the conditions under which ‘> 
the message appeared to your computer 

dealer. 


Line nnnnn is undefined 
A statement or command in the program 
refers to a line that doesn’t exist. 


Check the line references in your program so 
they all refer to actual program lines. 


Memory Overflow 
The compiler working memory is exhausted. 
The program is too large to compile 
successfully. 


Try compiling the program again with the /S 
parameter to reduce compiler working 
memory requirements or break the program 
up into smaller programs. 


Missing NEXT for z 
No NEXT statement was found for the 
variable z. 


Correct the static nesting of your FOR and 
NEXT statements. 
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Listing Errors 


The compiler lists all the errors it finds in your source 
listing file as follows: the compiler outputs the line 
containing the error with an arrow beneath that line 
pointing to the place in the line where the error 
occurred, and the two-character code for the error. In 
some cases, the compiler reads ahead on a line to 
determine whether an error has actually occurred. In 
those cases, the arrow points a few characters beyond 
the error, or to the end of the line. 


Some of the compiletime error codes are only warning 
messages; warnings do not need to be corrected before 
you go on to the linking step. If a message is a warning, 
it is noted in the explanation for the message. If the 
explanation does not say that the message is only a 
warning, the message indicates a severe error that must 
be corrected. 


Code Message and Meaning 


BS Bad subscript 
An array reference had an invalid dimension 
value (such as a noninteger value) or the 
wrong number of subscripts. 


CD COMMON duplication 
A variable appeared more than once in the 
COMMON statement(s) in the program. 


CN COMMON array not dimensioned 
An array ina COMMON statement had not 
been dimensioned when the COMMON 
statement was encountered. 


An array passed in a COMMON statement 
must be defined in a DIM statement that 
precedes the COMMON statement. 


CO 


DD 


FD 


FN 


IN 


LL 


COMMON out of order 
The COMMON statement was found after 
executable statements in the program. 


COMMON must precede any executable 
statements. 


Duplicate Definition 

You tried to define the size of the same array 
twice. This may happen in one of several 
ways: 


e The same array is defined in two DIM 
statements. 

e The program encounters a DIM 
statement for an array after the default 
dimension of 10 is established for that 
array. 

e The program sees an OPTION BASE 
statement after an array has been 
dimensioned, either by a DIM statement 
or by default. 


Function already defined 

You used DEF FN to define a function with 
the same name as a function previously 
defined in your program. 


FOR...NEXT error 

The counter variable on a FOR statement is 
already in use, or a FOR statement does not 
have a corresponding NEXT, or a NEXT 
was encountered without a corresponding 
FOR. 


INCLUDE error 
The file specified in the $INCLUDE 
metacommand could not be found. 


Line too long 
A line has too many characters. 


The line must have 253 characters or fewer. 


LS String constant too long 
You tried to create a string constant that is 
more than 255 characters long. 


MC Metacommand error 
The format of a metacommand was invalid or 
included an invalid argument. The 
metacommand is ignored. This message is 
only a warning. 


ND Array not dimensioned 
Default dimensions were assigned to the 
array. This message is only a warning. 


OM Out of memory 
A program has too many statement numbers, 
or program memory is too full, or data 
memory may be overflowing, possibly 
because an array is too big. 


OV Overflow 
A constant was not within the range 
expected by the compiler. Or an expression 
containing constants was calculated by the 
compiler and resulted in an overflow. One 
way to correct this is may be use 
single-precision constants instead of integer 
constants. 


SB Caused by one of the following: 


e Subprogram definition error 

e Subprogram alread defined 

¢« Incorrectly nested SUB/END 
SUB/EXIT SUB 


SI Statement ignored 
The statement was ignored by the compiler. 


unimplemented. This message is only a 


Y It may be that the command is 
warning. 


SN Syntax error 
Caused by one of the following: 


Invalid argument name 
Invalid assignment target 
Invalid constant format 
Invalid DEFtype character specification ‘y 
Invalid expression syntax 

Invalid function name 

Invalid function formal parameter 

Invalid separator 

Invalid format for statement number 

Invalid character 

Missing AS 

Missing equal sign 

Missing GOTO or GOSUB 

Missing comma 

Missing INPUT 

Missing line number 

Missing left parenthesis 

Missing minus sign 

Missing operand in expression 

Missing right parenthesis “a 
Missing semicolon 

Name too long 

Expected GOTO or GOSUB 
String assignment required 

String expression required 

String variable required 

Invalid syntax 

Variable required 

Wrong number of arguments 
Formal parameters must be unique 
Single variable only allowed 
Missing TO 

Invalid FOR loop index variable 
Missing THEN 

Missing BASE 

Invalid subroutine name. 
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SQ 


ST 


TC 


TM 


UC 


UF 


WE 


/0 


Sequence error 

The line numbers in your program were not 
in sequence, or contained a duplicate 
statement number. 


Missing STATIC on SUB statement. 


Too complex 

An expression is too complex, there are too 
many arguments in a function call, there are 
too many dimensions in an array, there is 
more than one variable for LINE INPUT, 
there are too many variables for INPUT, or 
the memory limit was exceeded. 


The compiler has a limit of 60 arguments for 
a function call, and 60 variables in an INPUT 
statement. 


Type mismatch 
The variable is not of the required type 
(numeric or string). 


Unrecognizable command 

The statement is unrecognizable or the 
command is not implemented. It may be that 
you used a built-in function on the left side 
of an equal sign. 


Undefined user function 
You called a function before defining it with 
the DEF FN statement. 


WHILE...WEND error 

A WHILE does not have a matching WEND, 
or a WEND was encountered before a 
matching WHILE. 


Division by zero 


You tried to divide by zero, or you had a 
divide overflow. 
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/E Missing /E parameter 
Your program included a RESUME /Jine 
statement. 


It must be recompiled with the /E parameter. 
If the listing also contains a /X error, 
recompile using /X instead of /E. ‘> 


/V Missing /V parameter 
The program contains event trapping 
statements. 


Recompile the program using either of the 
event trapping parameters, /V or /W. 


/X Missing /X parameter 
Your program included a RESUME 0, 
RESUME, or RESUME NEXT statement. 


It must be recompiled with the /X parameter. 
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Errors while Running a Program 


The following errors may occur when you run your 

compiled and linked program. The first group of errors 

can be trapped by using an ON ERROR statement. 
‘oe The error numbers match those issued by the BASIC 
interpreter. When an untrapped error occurs, the 
message is displayed followed by an address. If the /D, 
/E, or /X parameter was specified to the compiler, the 
number of the line in which the error occurred is 
displayed instead. 


Number Message 


2 Syntax error 
A string item was encountered ina DATA 
statement when the program wanted a 
numeric value. 


Correct the DATA statement or the READ 
statement. 


Or, you may have the wrong number of 
arguments in a COLOR, LOCATE, or 
SCREEN statement. 


3 RETURN without GOSUB 
A RETURN statement needs a previous 
unmatched GOSUB statement. 


Correct the program. You probably need to 
put a STOP or END statement before the 
subroutine so the program does not “‘fall’’ 
into the subroutine code. 


4 Out of DATA 
A READ statement is trying to read more 
data than is in the DATA statements. 


Correct the program so that there are enough 
constants in the DATA statements for all the 
READ statements in the program. 
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5 Illegal function call 
A parameter that is out of range is passed to 
a system function. The error may also occur 
as the result of: 


e A negative or unreasonably large 
subscript 

e Trying to raise a negative number to a 
power that is not an integer 

e Calling a USR function before defining 
the starting address with DEF USR 

e A negative record number on GET or 
PUT (file) 

e An improper argument to a function or 
statement (such as one that is out of the 
expected range for the parameter) 

e Trying to concatenate strings where the 
result is more than 32767 characters 
long 


Correct the program. Refer to particular 
statement or function for more information. ~ 


6 Overflow 
The magnitude of a number is too large to be 
represented in the required number format. 
Unlike the interpreter, execution always 
stops when this error occurs. 


You may be able to change the order of 
operations in a calculation so the overflow 
doesn’t occur; or you may have to restrict the 
range of numbers in the program to avoid the 
overflow. To correct integer overflow, you 
may try changing to single-precision or 
double-precision variables. 


Note: As with the interpreter, if 


underflow occurs, the result is zero and 
execution continues without an error. 
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11 


13 


14 


16 


Out of memory 

There is not enough free memory to allocate 
file buffers, communications buffers, and/or 
the music background buffer. Or you may be 
doing complex painting, or you may have too 
many GOSUBs. 


Subscript out of range 
You used an array element with a subscript 
that is outside the dimensions of the array. 


Check the usage of the array variable. 


Division by zero 

In an expression, you tried to divide by zero, 
you tried to raise zero to a negative power, or 
you had an integer divide overflow. 


Type mismatch 

You gave a string value where a numeric 
value was expected, or you had a numeric 
value in place of a string value. This may 
occur in DRAW or PLAY with VARPTR$, 
or in a PRINT USING statement. 


Out of string space 

String variables exceed the amount of 
remaining free string space after 
housecleaning. 


String formula too complex 
A string expression is too long or too 
complex. 


The expression should be broken into smaller 
expressions. 


Or more than 15 string variables were 
requested in an input statement. 
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19 No RESUME 
The physical end of the program was 
encountered while the program was in an 
error trapping routine. 


Correct the error trapping routine so a a) 
RESUME statement is executed. Or you 

may want to add an ON ERROR GOTO 0 
statement to the error trapping routine so 

BASIC will display the message for any 

uncaught error. 


20 RESUME without error 
The program has encountered a RESUME 
statement without having trapped an error. 
The error trapping routine should only be 
entered when an error occurs or an ERROR 
statement is executed. 


You probably need to include a STOP or 
END statement before the error trapping 
routine to prevent the program from “‘falling 
into”’ the error trapping code. 


24 Device Timeout 
BASIC did not receive information from an 
input/output device within a predetermined 
amount of time. 


For a communications file, this indicates that 
one of the signals tested by OPEN “COM... 
is off. 


Zo Device Fault 
A hardware error indication was returned by 
an interface adapter. 


For communications files, this error may also 
occur when one of the signals tested by “& 
OPEN ‘‘COM... is lost. 
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27 


50 


51 


Out of Paper 
The printer is out of paper, or the printer is 
not switched on. 


You should insert paper (if necessary), verify 
that the printer is properly connected, and 
make sure that the power is on. Then restart 
the program or continue the error trapping 
routine. 


FIELD overflow 

A FIELD statement is attempting to allocate 
more bytes than were specified for the record 
length of a random file in the OPEN 
statement. Or, the end of the FIELD buffer 
is encountered while doing sequential I/O 
(PRINT #, WRITE #, INPUT #) toa 
random file. 


Check the OPEN statement and the FIELD 
statement to make sure they correspond. If 
you are doing sequential I/O to a random 
file, make sure that the length of the data 
read or written does not exceed the record 
length of the random file. 


Internal error 
An internal malfunction occurred in the 
BASIC Compiler 2.00 runtime. 


Recopy your compiler diskette. Check the 
hardware and retry the compile. If the error 
reoccurs, report the conditions under which 
the message appeared to your computer 
dealer. 
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52 Bad file number 
A statement uses a file number of a file that 
is not open, or the file number is not in the 
range 1 to 127. Or, the device name in the 
file specification is too long or invalid, or the 
filename was too long or invalid. 


Make sure the file you wanted was opened 
and that the file number was entered 
correctly in the statement. Check that you 
have a valid file specification (refer to 
‘‘Naming Files” in BASIC Compiler 2.00 
Fundamentals for information on file 
specifications). 


53 File not found 
A KILL, NAME, FILES, or OPEN 
references a file that does not exist on the 
diskette in the specified drive. 


Verify that the correct diskette is in the drive 
specified, and that the file specification was 
entered correctly. Then retry the operation. ~» 


54 Bad file mode 
You tried to use PUT or GET witha 
sequential file or a closed file; or to execute 
an OPEN with a file mode other than input, 
output, append, or random. 


Make sure the OPEN statement was entered 
and executed properly. GET and PUT 
require a random file. 


55 File already open 
You tried to open a file for sequential output 
or append, and the file is already opened; or, 
you tried to use KILL on a file that is open. 


Make sure you only execute one OPEN to a “» 
file if you are writing to it sequentially. 
Close a file before you use KILL. 
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58 


61 


62 


Device I/O Error 
An error occurred on a device I/O operation. 
DOS cannot recover from the error. 


This error may occur with communications 
files, from overrun, framing, break, or parity 
errors. If you are communicating with 7 or 
less data bits, the eighth is turned on in the 
byte in error. 


File already exists 

The filename specified in a NAME statement 
matches a filename already in use on the 
diskette. 


Retry the NAME command using a different 
name. 


Disk full 
All diskette storage space is in use. Files are 
closed when this error occurs. 


If there are any files on the diskette that you 
no longer need, erase them or use a new 
diskette. Then rerun the program. 


Input past end 

This is an end of file error. An input 
statement is executed for a null (empty) file, 
or after all the data in a sequential file was 
already input. 


To avoid this error, use the EOF function to 
detect the end of file. 


This error also occurs if you try to read from 
a file that was opened for output or append. If 
you want to read from a sequential output (or 
append) file, you must close it and open it 
again for input. 
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68 
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Bad record number 

Ina PUT, GET, LOCK, or UNLOCK 
statement, the record number is equal to 
zero. 


Correct the statement to use a valid record 
number. 


Bad file name 

An invalid form is used for the filename with 
BLOAD, BSAVE, KILL, OPEN, NAME, 
or FILES. 


Check “‘Naming Files” in BASIC Compiler 
Fundamentals for information on valid 
filenames, and correct the filename in error. 


Too many files 

An attempt is made to create a new file 
(using OPEN) when all directory entries on 
the diskette are full, or when the file 
specification is invalid. 


If the file specification is okay, use a new 
formatted diskette and retry the operation. 


Device Unavailable 

You tried to open a file to a device that does 
not exist. Either you do not have the 
hardware to support the device (such as 
printer adapters for a second or third 
printer), or you have disabled the device. 
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70 


Communication buffer overflow 

A communication input statement was 
executed, but the input buffer was already 
full. You should use an ON ERROR 
statement to retry the input when this 
condition occurs. Subsequent inputs attempt 
to clear this fault unless characters continue 
to be received faster than the program can 
process them. If this happens there are 
several possible solutions: 


e Increase the size of the communications 
buffer using the /C parameter when you 
start the BASIC Compiler 2.00. 


« Implement a “‘hand-shaking”’ protocol 
with the other computer to tell it to stop 
sending long enough so you can catch up. 
(See the example in Appendix B, 
**“Communications”’ of the BASIC 
Compiler Fundamentals.) 


e Use a lower baud rate to transmit and 
receive. 


Permission Denied 

You tried to write to a diskette that is 
write-protected. Make sure you are using the 
right diskette. If so, remove the write 
protection, then retry the operation. Or, you 
attempted to write or read a record that has 
been LOCKed by another process. Retry the 
process when the other process has unlocked 
the record. Or, during an OPEN, you 
violated one of the sharing attributes of the 
file you are opening. Retry the OPEN with 
the correct sharing attribute. 
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72 


73 


74 


75 


Disk not Ready 
The diskette drive door is open or a diskette 
is not in the drive. 


Disk Media Error 

The controller attachment card detected a 
hardware or media fault. Usually, this means 
that the diskette has gone bad. Copy any 
existing files to a new diskette and re-format 
the bad diskette. If formatting fails, the 
diskette should be discarded. 


Advanced Feature 
You tried to use PCjr only features on a 
different system. 


Rename Across Disks 

You tried to rename a file but specified the 
wrong disk. The RENAME operation is not 
performed. When you use RENAME, the 
drive you specify must be the same for the old 
filename and the new filename. The exception 
to this is when the DOS ASSIGN command 
is active. The drive can be logically different, 
but must be the same physical drive. 


Path/file access error 

During an OPEN, RENAME, MKDIR, 
CHDIR or RMDIR operation, an attempt 
was made to use a path or filename to an 
inaccessible file. For example, you tried to 
open a directory or volume identifier; you 
tried to open a read only file for writing; or 
you tried to remove the current directory. The 
operation is not completed. 


You attempted to read or write to a file 
opened by another process which has denied 
read or write access to other processes. 
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Path not found 

During an OPEN, MKDIR, CHDIR or 
RMDIR operation, DOS is unable to find the 
path the way it is specified. The operation is 
not completed. 


\& The following error messages are not numbered. 


Incorrect DOS version 
BASIC Compiler 2.00 requires DOS 2.10 or 
later. 


Unprintable error 

This message occurs whenever an error 
message is not available for the error 
condition that exists. This is usually caused 
by an ERROR statement with an undefined 
error code. 


Check your program to make sure you handle 
all error codes that you create. 


You cannot SHELL to BASIC. 
BASIC cannot be run as a child process. 


A-23 


Errors That Cannot Be Trapped 


The following additional runtime error messages are 
unrecoverable and cannot be trapped: 


Message Meaning 


Cannot Relocate Memory After SHELL 
For programs that use the runtime module, 
following the execution of a CLEAR 
statement on the PCjr or a SHELL 
statement, the runtime module could not be 
loaded into memory. This is a fatal error 
which leaves the BIOS flag in the “BASIC 
executing” state. You must reboot before 
running another program. 


Error in EXE file 
The indicated file is in the wrong format. It 
should be an executable (.EXE) file. This 
may happen with RUN, CHAIN, and when 
loading BASRUN20.EXE. 


This error also occurs when a program that A 
uses the BASRUN20.EXE runtime module 

tries to chain to a executable program which 

does not use BASRUN20.EXE. 


Internal Error - No Line Number 
This error occurs when the error address 
cannot be found in the line number table 
during error trapping. 


Internal Error - String Space Corrupt 


Internal Error - String Space Corrupt during G.C. 
These two errors usually occur because a 
string descriptor has been improperly 
modified. (G.C. stands for garbage collection, 
which is the same thing as housecleaning.) “” 
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No Environment for SHELL 
The SHELL processor could not find the 
‘““COMSPEC” environment variable for the 
Command.Com file. This is a fatal error. 


Program too large 
The file is too large to load into memory. 
& This may happen when chaining from a 
program that uses the runtime module, and 
when loading BASRUN20.EXE. 


Wrong Version of Runtime Module 
An attempt was made to load an incorrect 
version of the runtime module into memory. 
This is a fatal error. 
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Appendix B. ASCIT Character Codes 


Y The following table lists all the ASCII codes (in 

decimal) and their associated characters. These 
characters can be displayed using PRINT CHR$(n) 
where n is the ASCII code. 


Some of the entries for ASCII codes 0 to 31 and 135 to 
155 also indicate the control function associated with 
that character. For example, ASCII code 27 displays a 
left arrow, and is also recognized as an ESCape control 
character. 


Each of these characters can be entered from the 
keyboard by pressing and holding the Alt key, then 
pressing the digits for the ASCII code on the numeric 
keypad. Note, however, that some of the codes have 
special meaning to the BASIC program editor supplied 
with the interpreter —the program editor uses its own 
interpretation for the codes and may not display the 
special character listed here. 


010 011 012 013 014 015 016 017 018 019 


020 021 022 023 024 025 026 027 028 029 


DC4 | NAK| SYN 


030 031 032 033 034 035 036 037 038 039 


+ 
ti 
ox 


040 041 042 043 044 


o 
- 
a 
°o 
b 
o 
(oe) 
oS 
~ 
o 
h 
© 


049 


050 051 052 053 054 055 056 057 058 059 


060 061 062 063 064 065 066 067 068 069 


070 071 O72 073 074 075 076 077 078 079 


080 081 082 083 084 085 086 087 088 089 


090 091 092 093 094 095 096 097 098 099 


100 101 


a 
{o) 
Le) 
—< 
°o 
o 
anil 
fe) 
psy 
a 
(eo) 
a 
ah 
(eo) 
o 
= 
{2) 
~ 
eee 
je) 
tee) 
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a 
aa 
a 
= 
ak 
Le) 
= 
= 
() 
ae 
a 
psy 
a 
az 
a 
=i 
— 
o 
aks 
a 
~“ 
a 
ih 
© 


Ee. 
= 
°o 
> 
re] 
ii 
— 
© 


120 121 


122 123 124 125 126 127 
wielliiiip jo 


128 129 


130 131 132 133 134 135 136 137 138 


140 141 142 143 144 145 146 147 148 
150 151 152 153 154 155 156 157 158 159 


180 181 182 183. ~-184 185 186 187 188 189 


200 201 202 203 


210 241 212 213 


220 221 222 223 


230 231 


250 


251 252 253 254 255 


Extended Codes 


For certain keys or key combinations that cannot be 
represented in standard ASCII code, an extended code 
is returned by the INKEY$ system variable. A null 

character (ASCII code OOO) is returned as the first ‘> 
character of a two-character string. If a two-character 

string is received by INKEY$, you should go back and 
examine the second character to determine the actual 

key pressed. Usually, but not always, this second code 

is the scan code of the primary key that was pressed. 

The ASCII codes (in decimal) for this second character, 

and the associated key(s) are listed below. 


Second Code Meaning 


3 (null character) NUL 
15 (shift tab) |}<— 
16-25 Alt- Q,W,E,R,T,Y,U,I,0O,P 
30-38 Alt- A,S,D,F,G,H,J,K,L “& 
44-50 Alt- Z,X,C,V,B,N,M 
59-68 function keys Fn plus F1 through F10 
(when disabled as soft keys) 
71 Fn/Home 
te Home 
13 Fn/Pg Up 
I? Pg Up 
77 Pg Dn a) 
79 Fn/End 
80 End 


81 


82 


83 


84-93 


94-103 


104-113 


114 


a 


116 


117 


118 


ey 


120-131 


is 


Fn/Pg Dn 

Ins 

Del 

F11-F20 (Shift-Fn/F1 through F10) 
F21-F30 (Ctrl-Fn/F1 through F10) 
F31-F40 (Alt-Fn/F1 through F10) 
Fn/PrtSc 

Ctrl-Pg Up (Previous Word) 
Ctrl-Pg Dn (Next Word) 
Ctrl-Fn/End 

Ctrl-Fn/Pg Dn 

Ctrl-Fn/Home 

Alt- 1,2,3,4,5,6,7,8,9,0,-,= 


Ctrl-Fn/Pg Up 


C-1 


p02 ee One 


v 
= | 
5 

A 
a 
\) 
NM & 


Scan code Key 

in hex 

01 ee 
— 


Key 


Appendix C. Scan Codes 


Scan code 
in hex 


Scan code 
in hex 


|e 


Scan code 
in hex 


Scan code 
in hex 
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Index 


Special Characters A 


$DYNAMIC A parameter 11 
Metacommand 2 ABS 20 
S$INCLUDE Metacommand 4 ABS Function 20 
S$LINESIZE Metacommand 8 absolute value 20 


$LIST Metacommand 9 active page 386 
$MODULE 10 aliasing of variables 33 
S$MODULE ampersand symbol 333 
Metacommand 10 animation 351 
$OCODE Metacommand 11 append 271 
$PAGE 12 arctangent 22 
SPAGE Metacommand 12 arrays 103, 127, 289 
S$PAGEIF 13 ASO 2a 
S$PAGEIF Metacommand 13 ASC Function 21 
S$PAGESIZE 14 ASCII character codes B-1 
$PAGESIZE ASCII code 382 
Metacommand 14 ASCII codes 21, 45 
SSKIP 15 converting to 21 
S$SKIP Metacommand 15 aspect ratio 51,113 
$STATIC 16 assembly language 
S$STATIC Metacommand 16 subroutines 31 
$SUBTITLE assignment statement 200 
Metacommand 18 ATN 22 
$TITLE Metacommand 19 ATN Function 22 
E133 
fq. 453 
?Redo from start 173 
350 B 
& background 64, 293 
BASIC program editor 5, 329 
question mark for 
PRINT 329 


Index-1 


BEEP 24 

BEEP Statement 24 
blinking characters 67 
BLOAD 26 

BLOAD Command 26 
border screen 64 
boundary 293, 450 
branching 159, 248 
BSAVE 29 

BSAVE Command 29 
burst, screen 384 


C 


CALL 31 

CALL ABSOLUTE 38 

CALL ABSOLUTE 
Statement 38 

CALL Statement 31 
CALLS 36 

CALLS Statement 36 

cassette motor 235 
CDBL 40 

CDBL Function 40 

CHAIN 41,78 

CHAIN Statement 41 

change current directory 43 

CHDIR 43 

CHDIR Command 43 

child process 123, 395 

CHR$ 45 

CHR$ Function 45 

CINT 47 

CINT Function 47 

CIRCLE 48 

CIRCLE Statement 48 

CLEAR 54 

CLEAR Command 54 

clear screen 62 

clear system buffer 365 
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clock vii, 400 
CLOSE 60 
close disk files 365 
CLOSE Statement 60, 365 
CLS 62 
CLS Statement 62 
color 345, 449 
COLOR Statement 64, 291, 
383 
COM 74 
COM(n) Statement 74 
comma in formatting 
String 338 
COMMANDS 76 
COMMANDS Function 76 
comments 363 
COMMON 41, 78 
COMMON Statement 78 
communications 282 
communications buffer 284 
communications trapping 74, 
241 
compiletime errors A-7 
computed 
GOSUB/GOTO 248 
converting degrees to 
radians 83 
converting from numbers for 
random files 233 
converting from numeric to 
octal 240 
converting numbers 40 
converting numbers from 
random files 86 
converting radians to 
degrees 22 
converting string to 
numeric 443 
converting to integer 47 
coordinates 
physical 461 
world 461 


coordinates, absolute or 
relative form 291, 345 

COS 83 

COS Function 83 

cosine 83 

create a directory 231 

creating tree structure 231 

CSNG 84 

CSNG Function 84 

CSRLIN 85 

CSRLIN Variable 85 

cursor position 85, 213, 328 

CVICVS, CVD: 86 

CVI, CVS, CVD Functions 8&6 


D 


DATA 88, 358 

data segment 97, 101 

DATA Statement 88 

DATES 90 

DATE$ Variable and 
Statement 90 

decisions 163 

declaring arrays 103 

declaring variable types 99 

DEF FN 92 

DEF FN and END DEF and 
EXIT DEF Statements 92 

DEF SEG 97 

DEF SEG Statement 97 

DEF USR 101 

DEF USR Statement 101 

DEFtype Statements 99 

deleting a file 193 

deleting arrays 127 

Device timeout 224 

DIM Statement 103 

dimensioning arrays 103 

DIR 139 


direct mode 246 

directory 43 

display pages 386 

division by zero A-15 

documentation, internal 
program 363 

double asterisk 336 

double asterisk, dollar sign 337 

double dollar sign 337 

double-precision 40 

DRAW Statement 107 

DS (compiler’s DATA 
segment) 97 

duration, time vii, 400 


E 


elapsed time 432 
ELSE 163 

END 117 

END DEF 92 

end of file 125 

END Statement 117 
END SUB 421 

ending BASIC 426 
ENVIRON 118 
ENVIRON Statement 118 
ENVIRONS 121 
ENVIRONS Function 121 
environment 118, 121 
EOF 125 

EOF Function 125 
ERASE 127 

ERASE (DOS) 193 
ERASE Statement 127 
erasing a file 193 
erasing arrays 127 
erasing variables 54 
ERDEV 129 
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ERDEV and ERDEV$ 
Variables 129 
ERL 131 
ERR 131 
ERR and ERL Variables 131 
ERROR 133 
error codes 131, 133, 
Appendix A 
error line 131 
ERROR Statement 133 
error trapping 131, 133, 245, 
368, A-13, A-24 
errors messages A-4 
errors, compiletime A-7 
errors, runtime A-3 
event trapping 191 
Ree) 191,251 
ON PLAY(n) 259 
ON TIMER 267 
PEN 256, 308 
STRIG(n) (joystick 
button) 263 
exchanging variables 425 
exclamation point symbol 333 
executing a program 379 
exit BASIC 426 
EXIT DEF 92 
EXP 135 
EXP Function 135 
exponential function 135 


F 


false or true 382 

FIELD 136 

FIELD Statement 136 

File access control 216, 438 
file size 218 

file, position of 211 

FILES Command 139 
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FILES 139 

FIX 142 

FIX Function 142 

fixed-length strings 226 

floor function 182 

FOR 143 

FOR and NEXT 
Statements 143 

foreground 64 

formatting 332 

FRE 148 

FRE Function 148 

free space 54, 148 

frequency vii, 400 

frequency table 403 

function keys 186 


G 


garbage collection 148 
GET (files) 150 
GET (graphics) 152 
GET Statement (Files) 150 
GET Statement 
(Graphics) 152 
glissando 404 
GOSUB 156, 248 
GOSUB and RETURN 
Statements 156 
GOTO 159, 248 
GOTO Statement 159 
GRAFTABL Command 388 
GRAPHICS 
CIRCLE 48 
COLOR 70 
GET 152 
PAINT 291 
POINT function 323 
PSET and PRESET 345 
PUT 350 


VIEW 448 
WINDOW 461 
graphics statements 107, 202 
DRAW 107 
LINE 202 


H 


HEX$ 162 

HEX$ Function 162 
hexadecimal 162 
high-intensity characters 67 
housecleaning 148 


I/O control 183 

IF 163 

IF Statement 163 
imbedding files 4 

indent 427 

index (position in string) 180 
INKEY$ 169 

INKEY$ Variable 169 
INP 171 

INP Function 171 
INPUT 172 

INPUT Statement 176 
INPUT # 176 

input editor 173, 208 
input file mode 271 
INPUT Statement 172 
INPUTS 178 

INPUTS Function 178 
INSTR 180 

INSTR Function 180 


INT 182 

INT Function 182 
integer 

IOCTL 183 

IOCTL Statement 183 
IOCTLS$ 185 

IOCTL$ Function 185 


J 


joystick 411 
joystick button 263, 416, 418 
jumping 159, 248 


K 


KEY 186 

KEY Statement 186 
KEY(n) 191 

KEY(n) Statement 191 
KILL 193 

KILL Command 193 


L 


labels 156, 159 
LBOUND 195 
LBOUND Function 195 
LEFT$ 198 

LEFT$ Function 198 
left-justify 226 

LEN 199 
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LEN Function 199 
length of file 218 
length of string 199 
LET 200 
LET Statement 200 
light pen 256, 308 
LINE 202 
line drawing in graphics 202 
line feed 274 
LINE INPUT 207 
LINE INPUT Statement 209 
LINE INPUT # 209 
LINE INPUT Statement 207 
line numbers 5 
LINE Statement 202 
line styling 203 
$LINESIZE 8 
listing files 139 

on disk 139 
loading binary data 26 
47. 211 
LOC Function 211 
LOCATE 213 
LOCATE Statement 213 
LOCK 216 
LOCK Statement 216 
LOF 218 
LOF Function 218 
LOG 220 
LOG Function 220 
logarithm 220 
long messages A-4 
loops 143, 455 
LPOS .222 
LPOS Function 222 
LPRINT 223 
LPRINT and LPRINT USING 

Statements 223 

LPRINT Statement 331 
LPRINT USING 223 
| do Uh BER At ee PA, 
LSET 226 
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LSET and RSET 
Statements 226 


M 


machine input port status 453 
machine language 
subprograms 38 
machine language 
subroutines 31, 36 
memory image 29 
MERGE 41 
metacommands 1 
S$DYNAMIC 2 
SINCLUDE 4 
$LINESIZE 8 
$LIST 9 
SMODULE 10 
S$OCODE 11 
$PAGE 12 
S$PAGEIF 13 
$PAGESIZE 14 
$SKIP 15 
$STATIC 16 
S$SUBTITLE 18 
$STITLE 19 
MID$ 228 
MID$ Function and 
Statement 228 
minus sign 336 
MKDIR 231 
MKDIR Command 231 
MKI$, MKS$, MKD$ 233 
MKI$, MKS$, MKD$ 
Functions 233 
mode, screen 384 “ 
MOTOR Statement 235 
Multiline functions 94 
music 312, 403 


N 


NAME 236 

NAME Command 236 
NEXT 143 

NOISE 238 

noise generation 238 

NOISE Statement 238 
nontrappable errors A-24 
notes, sound 403 

number of notes in buffer 319 


O 


OCT$ 240 

OCT$ Function 240 

octal 240 

offset 97, 101 

ON COM(n) 241 

ON COM(n) Statement 241 

ON ERROR 245 

ON ERROR statement 133, 
245 

ON KEY(n) 251 

ON KEY(n) Statement 251 

ON PEN 256 

ON PEN Statement 256 

ON PLAY(n) 259 

ON PLAY(n) Statement 259 

ON STRIG(n) 263 

ON STRIG(n) Statement 263 

ON TIMER Statement 267 

ON TIMER(n) 267 

ON...GOSUB 248 

ON...GOSUB and ON...GOTO 
Statements 248 

ON...GOTO 248 

OPEN 271 


orem COM... 
Statement 282 
OPEN ‘“‘COM... 282 
OPEN Statement 271 
opening files 271 
opening paths 271 
OPTION BASE 289 
OPTION BASE 
Statement 289 
OUT 290 
OUT Statement 290 
output file mode 271 
overflow A-9, A-14 
overlay 41 


Pp 


$PAGE 12 

page, active 386 

page, visual 387 
S$PAGEIF 13 
S$PAGESIZE 14 
PAINT 291 

PAINT Statement 291 
paint tiling 298 
PALETTE viii, 70, 300 
PALETTE USING 
Statement 302 
PALETTE Statement viii, 300 
PALETTE USING 302 
panning 466 

passing variables 42 
paths 43 

paths, opening 271 
patterns 298 

PCOPY 305 

PCOPY Statement 305 
PEEK 306 

PEEK Function 306 
PEN 308 
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PEN OFF Statement 310 

PEN ON Statement 310 

PEN Statement and 
Function 308 

physical coordinates 462 

PLAY 312 

PLAY Statement 312 

PLAY(n) 319 

PLAY(n) Function 319 

plus sign 336 

PMAP 321 

PMAP Function 321 

POINT:.323 

POINT Function 323 

POKE 326 

POKE Statement 306, 326 

POS 328 

POS Function 328 

position in string 180 

position of file 211 

positioning the cursor 213 

precision 99 

PRESET 345 

PRINT 329 

PRINT and PRINT 
USING Statements 341 

PRINT # 341 

PRINT # USING 341 

print formatting 332 

PRINT Statement 329 

PRINT USING 332 

PRINT USING Statement 332 

print zones 329 

printing 223 

program editor 5 

program stop 413 

PSET 345 

PSET and PRESET 
Statements 345 

punctuation, PRINT 
Statement 329 

PUT (files) 348 

PUT (graphics) 350 


Index-8 


PUT Statement (Files) 348 
PUT Statement 
(Graphics) 350 


R 


random files 136, 150, 271 

random numbers 355, 376 

RANDOMIZE 355 

RANDOMIZE Statement 355 

READ 88, 358 

READ Statement 358 

REDIM 360 

REDIM Statement 360 

Redo 173 

REM 1, 363 

REM Statement 363 

remarks 363 

removing a directory 374 

RENAME 236 

renaming files 236 

repeating a string 419 

RESET 365 

RESET Command 365 

RESTORE 366 

RESTORE Statement 359, 
366 

RESUME 368 

RESUME Statement 368 

RETURN 156, 371 

RETURN Statement 371 

RIGHT$ 373 

RIGHTS$ Function 373 

right-justify 226 

RMDIR 374 

RMDIR Command 374 

RND 376 

RND Function 376 

rounding to an integer 47 

RSET 226 


RUN 379 
RUN Command 379 
runtime errors A-3, A-13 


S 


saving binary data 29 

scan codes Appendix C 

screen buffer address 30 

SCREEN Function 382 

SCREEN Statement 384 

seeding random number 
generator 355 

segment of storage 97 

sequential files 271 

SGN 392 

SGN Function 392 

SHARED 393 

SHARED attribute 79, 104, 
360 

SHARED Statement 393 

SHELL 395 

SHELL Statement 395 

sign of anumber 392 

SIN 399 

SIN Function 399 

sine 399 

single-precision 84 

$SKIP 15 

soft keys 186 

SOUND vii, 24, 400 

SOUND Statement vii, 24, 
400 

sounds vii, 24, 312, 400 

space 462 

SPACE$ 406 

SPACE$ Function 406 


spaces 330 
SPC 407 
SPC Function 407 
SOR 408 
SOR Function 408 
Square root 408 
Stack space 54 
Statement 470 
STATIC 409 
STATIC Statement 409 
STEP 143 
STICK 411 
STICK Function 411 
STOP 413 
STOP Statement 413 
STR$ 415 
converting from number to 
string 415 

STR$ Function 415 
STRIG 416 
STRIG Statement and 

Function 416 
STRIG(n) 418 
STRIG(n) Statement 418 
string space 54, 148 
STRINGS 419 
STRINGS Function 419 
SUB 421 
SUB and END SUB and EXIT 

SUB Statement 421 
subroutines 156, 248 
subscripts 103, 289 
substring 198, 228, 373 
Superimpose image 351 
SWAP 425 
SWAP Statement 425 
SYSTEM 426 
SYSTEM Command 426 
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T 


TAB 427 
TAB Function 427 
TAN 429 
TAN Function 429 
tangent 429 
tempo table 404 
terminating BASIC 426 
THEN 163 
This data segment 97 
tile painting 298 
tiling 294 
TIMES 430 
TIME$ Variable and 
Statement 430 
time, duration vii, 400 
TIMER 432 
TIMER Function and 
Statement 432 
trace 434 
transfer image 351 
trapping, communications 74 
tree-structured directories 
changing 43 
triggers, joystick 416 
trigonometric functions 
arctangent 22 
cosine 83 
trigonometric sine 399 
trigonometric tangent 429 
TROFF 434 
TRON 434 
TRON and TROFF 
Commands 434 
true or false 382 
truncation 142, 182 
turn off cassette player 235 
turn on cassette player 235 
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U 


UBOUND 436 
UBOUND Function 436 
underflow A-14 
UNLOCK 438 
UNLOCK Statement 438 
untrappable errors A-24 
user workspace 54, 148 
user-defined functions 92 
USR 101, 440 

USR Function 440 


V 


VAL 443 

VAL Function 443 
VARPTR 444 

VARPTR Function 444 
VARPTRS$ Function 446 
VIEW 448 

VIEW Statement 448, 461 
visual page 387 

vpage 387 


Ww 


WAIT 453 

WAIT Statement 453 
WEND 455 

WHILE 455 
WHILE and WEND 
Statements 455 
WIDTH 457 


WIDTH Statement 331, 457 7 
WINDOW 448, 461 
WINDOW Statement 461 


workspace 54, 148 zones, print 329 
world coordinates 461, 462 zooming 466 
WRITE 468 

WRITE # 470 


WRITE Statement 468 
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Language Reference 


Your comments assist us in improving the usefulness of 
our publication; they are an important part of the input 
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